In the first part of our new Docs As Code series, you will read about the philosophy behind the approach coupled with Quality Assurance, and how you can get started.
In the next parts, we will dive deeper into topics such as content strategy and design, defining values for checks, how to plan checks, implementation, tooling and continuous integration, deployment strategies and workflows.
Intro
Building, maintaining and continually improving documentation by doing Docs As Code the DocOps way.
Applying the Docs As Code method assumes that you use the same tooling (editor) for writing documentation which you use for working on your code.
In the same manner that code editors are configured with plugins for reporting coding style violations, you can configure your code editor with plugins that report inconsistencies with your company’s editorial and content style guides.
Depending on your documentation, these could be plugins for checking the consistency of your markup language, the style of headings, the length of documents and many more.
Consistent, tested documentation can help your product and your development cycle.
Consistency means that you write your documentation according to a defined standard reflecting your product and company. It also means that you can find information quickly, and understand that information when you encounter problems.
These are critical to quality.
Docs As Code breaks down into five points:
- Content strategy
- Editorial style guidelines
- Content analytics
- Automated testing
- Deploying (publishing).
Documentation Testing
Poor documentation reflects badly on the quality of the product and your company. A key part of the Docs As Code approach is to apply a Quality Assurance (QA) model in your documentation process.
This means running documentation tests in the same manner that developers run automated tests against the software they are writing.,
Documentation testing is a non-functional test of your content which helps ensure that it stays up-to-date with your product, the installation requirements, and is understandable by your audience.
Docs As Code done right saves you time and money by decreasing the time you spend fixing documentation and increasing its quality.
A word of advice
A deeper knowledge of engineering tools, workflows and a solid base and understanding of security is absolutely necessary to set up a Docs As Code way of working.
Working with Docs As Code can help you improve the quality and speed up the publication process, but it also has a learning curve.
It needs time to learn, understand and setting it up.
Make sure that all your tests are working, that you can trust the results, and that your infrastructure is well configured and secure.
Developers, DevOps, and your Site Reliability (SRE) teams can assist you to make sure everything is set up properly.
What is QA
Quality assurance (QA) is the process of verifying whether a product meets the required specifications and customer expectations (techopedia.com).
Why is QA important
Product documentation is an important marketing asset for promoting both your product and your organization.
Good documentation helps you to satisfy your customers.
Besides happy clients, it also means less support work and thus, more time for other projects. It will also save your company money.
Good documentation gets people to jump into your project quicker.
Where to start
Define your goals.
Editorial Style Guidelines
A good first step is to determine what you want to achieve.
Defining a style guide can help you with that.
A style guide refers to is a set of standards for the writing, formatting, and design of documents.
Style guides increase content consistency in tone, voice, wording, writing style, and branding.
Style is not a matter of right and wrong, but of what is appropriate for a particular setting and audience.
A style guide documents the basic rules that help to ensure consistency in any written or visual work.
Think of it as a set of standards everyone should follow.
These standards could be about fundamentals like grammar and punctuation or address structural elements of layout, typography, citations, and visual design.
Content Analytics
Content analytics can provide a broad and deep insight into the state of your docs and users.
This is helpful and needed for improvements of your content strategy.
By analyzing data you collect on your users’ behavior you can discover which content items are popular, how time users spend on articles, what they search for and much more.
People
Automated testing with Docs As Code can help you a lot to work more efficiently on quality improvements, still, it can not provide the human insight.
Grammatically correct and typo-free documentation does not warrant that your docs are excellent.
Ensure that your documentation is working, valid and understandable for your desired audience.
A good way to make sure that you have reached your goal is to test your docs with real human beings.
Ask (new) colleagues, your customers, you can even organize a community event to start testing your documentation.
Considerations
Start early.
Improving and fixing issues from the start is easier, faster, cheaper and more motivating because you see pleasing results and passing tests immediately.
This, in turn, could mean quicker publications (depending on your workflow).
Do not try to do too much in the beginning.
Start small, with a couple of checks and extend them later.
Keep in mind that setting up and getting used to checks and Docs As Code will take a while.
You will learn over time that some checks are not working the first time you introduce them, you will have to adjust them. This is part of the process!
A good approach, to begin with, is to test that your documentation contains no typos and all links are working.
Summary
In this article, we spoke about quality assurance and how QA can help to improve your documentation.
In the next part of the series, we will go deeper into content strategy, analytics, and analysis.
- Why is it important
- Why it is the foundation of a solid Docs As Code approach.
“If you don’t know what you want to or need to communicate, how will you know if you succeeded? This is where content strategy and design can help.” (Margot Bloomstein)
