In days past, DevPortals were often seen as an afterthought–just reference docs to accompany a business’s API program. Now, DevPortals are being recognized as a central hub necessary for interactions between your business and your customers, partners or vendors.
Many teams responsible for their company’s DevPortal are feeling the squeeze between the normal business demands to gain efficiencies and their customers’ need for documentation. Customers need to understand the API products being offered and need help to deliver results quickly.
While thinking about those competing demands, we used this webinar to explore how to improve your DocOps with a Docs-as-Code process to deploy and maintain documentation rapidly and ensure (and improve!) quality. We presented a high-level overview of the tools and techniques from modern code-development workflows, and showed how they can be adapted and applied to managing technical documentation. We took a closer look at Continuous Integration and Deployment (CI/CD) patterns and automated testing frameworks, and demonstrated ways to get started by using tools at the technical writer’s desktop.
Webinar Recap
- Why do you need Doc-Ops?
- What are the basic principles of DocOps?
- How does Docs-as-Code promote quality in documentation?
- Tools that can be used for implementing Docs-as-Code
- Tools that we use for our Docs-as-Code Demo
- Benefits of using command line for reviewing Docs-as-Code
- Description of Live Docs-as-Code Demo
- Docs-as-Code Demo Takeaways
- How to start a Docs-as-Code program
- Continue Your Journey - Recommended reading
Why do you need Doc-Ops?
- Encourage technical writers to work more closely with developers to promote better communication. Writers work in the same rhythm as the development team: synchronize your scrum sprints - new iteration, new release of documentation.
Sanity checks and user testing are important - do not automate everything. - By using the same tooling as developers, you can create better documentation by leveraging the same toolchains that are being used in development to help create documentation that is more accurate, consistent, and better enables the consumers of your documentation (developers).
- High-quality documentation establishes trust with downstream developers.
What are the basic principles of DocOps?
- Content Strategy - What should be documented and to whom? Where will the documentation be published? Can you use the same url paths in your local environment that are used on the deploy site?
- Editorial Style Guides - How does your company want to communicate? Use proper tone, preferred grammar, choice of words, abbreviations, and file formats.
- Automated Testing
- Automated Deployment
- Content Analytics - How is the content consumed?
Docs-as-Code needs editorial style guides but is defined by automated testing and automated deployment.
How does Docs-as-Code promote quality in documentation?
“Focus on things that actually add some value. And Docs Like Code: take engineering practices because that works really good for written content as well…” - Adam Bulter, @labfoo | DevRelCon - Feb, 2018
High-quality documentation is important for establishing trust with your downstream developers. Quality documentation is:
- free of functional errors, like broken links and missing images,
- synchronized with the functionality of your product: the content is accurate in that it reflects any recent changes,
- consistent with your organization’s style, so that it doesn’t read like an after-thought that was thrown together “because we had to have docs”,
- can be found easily by the potential readers/devs: tagged and keyword-rich,
- useful and easy (or even fun) to read.
Automated Testing can be used to run tests to find:
- spelling errors,
- unnecessary or missing punctuations, white spaces,
- syntax errors,
- broken links, missing or unused images,
- style-guide violations.
Errors and violations can be detected while writing by using your linters frequently.
Tools that can be used for implementing Docs-as-Code
- Travis CI
- GitHub
- Jenkins
- CircleCI
- GitLab
Tools that we use for our Docs-as-Code Demo
VS CODE
- Lightweight, powerful and free source code editor.
- Well-supported with extensions:
- for collaboration,
- text, code highlights,
- grammar- and syntax checks,
- Dark and light themes for different working conditions or taste.
- Customizable:
- preferences are in YAML format. For example, you can set the frequency of the auto-save feature by changing the value of a parameter. Most of the extensions are customizable, so you can combine their features together.
- It can be useful for both developers and writers.
- Vale is working with VS Code as an extension, but we are using Vale as a command line tool.
VALE
- A linter, designed to enforce an existing style guide through its YAML-based extension system.
- The extension system are collections of writing guidelines called styles. These guidelines are expressed through rules (YAML files). You don’t have to code anything.
- Check rule violations in the text in different aspects.
- Vale is compatible with many text editors as a resident, extension working in real-time, but can be used as a command-line tool. At Pronovix, our technical writer team uses Vale from the terminal.
Benefits of using Vale as a command-line tool for reviewing Docs-as-Code
As a technical writer you may use more than one tool to check your documentation: other spell checkers, like Write Good Linter, MD or code language syntax validators, readability testers, trailing whitespace highlighter.
We wanted to reuse the results for further analyses and we found it is easier to export them from the terminal. Command-line Vale is useful if you want to use Vale outside of VS Code or if you want to use Vale together with your own linter solutions, like custom URL path, resource image checkers. You can display all the results in the same window and can run them together at the same time.
In our setup, Vale runs on every save: makes it possible to detect errors and violations during writing.
Description of Live Docs-as-Code Demo
Let’s suppose, there is some old documentation on the developer portal of an imaginary company related to one of their API products called Moon Rover Photos. The text is in CommonMark-flavoured MD format. According to recent feedback from a user, it contains a broken link and some other typos. The technical or content writer team is going to pull the current state of the documentation using Git, then they’ll open the file with VS Code. Let’s assume that the company finished working on its style guide after this document is published. The editorial team has Vale set up on their computers with rule checkers based on their style guide. They can run automated tests to find all errors and style-guide violations left in the text. After the corrections, one of the team members can commit the changes and publish the text again.
Docs-as-Code Demo Takeaways
- Create a style guide according to your company’s standards.
- Start using automated tests as soon as possible.
- Create custom scripts and rules.
- Write meaningful warning messages.
- Don’t automate everything.
- Never stop testing: look for false alarms and edge cases.
- Keep your styles safe, in a repository.
How to start a Docs-as-Code program
- Develop your Foundations: Content Strategy, Editorial Style Guidelines, Content Analytics.
- Evaluate your DevPortal: Non-technical Contributors, Technical Writers, Developers.
- Change Management: Every organization is different - Engage with your stakeholders and internal customers to get their support.
- Partner with & leverage your development team: Investigate their tools and see what you may be able to integrate with. Do they have a sandbox?
- Start small & grow: Instead of trying a big-bang approach, find a pain-point that you can resolve, and build on your success.
- Communities: There are many people passionate about these topics that will help you along the way. Remember to pay it forward.
Continue Your Journey - Recommended reading
List of Reference Styleguides
- Google developer documentation style guide
- Splunk Style Guide
- developerWorks editorial style guide (IBM developerWorks, May 2014)
- The Red Hat Style Guide - Conventions for Writers and Editors
- The Handy List of Human Words By Deanna Horton (Medium, Oct 2019)
- Use simple words and phrases (plainlanguage.gov)
Looking for some inspiration?
- “Docs-like-code” or “Docs-as-code” - Is it worth the hassle? By Saravana Kumar Dept 2019
- Test-the-docs GitHub site with Vale checkers
Credits
Webinar content was co-authored by Adam Balogh. Many thanks to Diliny Corlosquet for pulling the recap together and to Laura Vass for providing editorial feedback for the article!
