8.5 KiB
Write documentation like you develop code
Don't want documentation to be an afterthought? Try a new approach.
Many engineers and craftspeople are particular about their tools. To do a job well, you need the best tools and the skills to use them. The best tools in software development can be very powerful when applied to other kinds of digital creation. The Docs as Code approach is a great example. Docs as Code entails writing documentation using the same tools and workflows used for developing code. Proponents of Docs as Code report that this method leads to better documentation while easing the workload of the people who write it.
Text formats and source control
The most significant adjustment when moving from a more traditional documentation platform to the Docs as Code approach is that the content is stored in a text-based markup format. This change makes all the tools for text-based materials available for generating documentation. Whether you choose DocBook, Markdown, or another markup language, the transition from using just one tool to using a standard format and a variety of tools is a big change.
Finding tools that support your workflow is really important. Many developers use their coding editors when working on Docs as Code projects. Since they are already advanced-level users with that tool, it works well for them. Finding tooling that fits the other professionals on the team, such as technical writers, editors, information architects, and documentation product owners, may take more effort. A few options to consider:
- One of the many good markdown editors available
- Coding editors with good preview tools, which make them approachable for non-coders
- The web interfaces of popular Git hosting services, especially for occasional contributors
Once content is safely in a markup format, the project can use source control such as Git, an open source tool with many more features than most documentation platforms can claim:
- A clear and detailed version history of who changed what and when. If you have good commit message culture, you may even be able to learn why the change was made.
- Easy parallel change processes. Working in branches in Git means everyone can make all the changes they want to and combine them at the end.
- Advanced collaboration and review tooling. All the source-control platforms are designed to review each change in detail and have as much discussion as needed until everyone is confident that the change can go ahead.
- Automated quality checks such as spellchecking and link checking. This saves time and catches errors that might otherwise be missed.
Source control has many benefits. Just keep in mind that if you're new to source control, it has a learning curve. There are some excellent learning resources and articles for writers that can help. You can also let your curious documentarians find the learning materials that work for them rather than asking your engineers to teach them. (Ask me how I learned this—the hard way of course!)
Pull requests and review cycles
All source-control platforms are designed around the concept of pull requests, sometimes also called merge requests. Someone, or some team, puts together a set of changes and then requests that the changes are pulled into the main project. In many ways, working with many changes at once is easier in documentation than in code. Changing one article in one place in documentation has fewer side effects than when you change code and find that there were several other sections depending on it.
The most powerful collaboration tool is the diff, which shows the difference between old and new versions in a way that's easy to follow. There are many versions of this tool available to make the comparison view easier to look at: side-by-side, inline, or even as rendered markdown rather than just text. Each team member can use the tool or tools that work best for them. For example, the web view is commonly used to look at a small change, but for something bigger I would want to look at it locally using vimdiff or Meld.
Review comments can be added to the change as a whole or to individual lines in the proposed change. Some projects adopt a maximum line length, called a hard wrap, or start each sentence on a new line to make it easier to attach comments to specific parts of a block of text. Further changes and comments can be added until the review process is complete and the change is accepted. Since the pull requests are shown in a queue on the repository for the project, this is a good way to show what's in progress and what needs review attention. The tools make it easy for reviewers to add their thoughts. In particular, if you are working with technical audiences it can be easier to get reviews from these folks via the tools they use daily.
Continuous integration and deployment
Having the source of your documentation available in plain text has many benefits, such as making it easy to find every occurrence of something that needs changing and using existing tools such as wc, grep, or tree to work with potentially large document sets. When you combine this with a source-control platform, even more existing tools become available, and they're all open source.
One big workflow improvement is the ability to have continuous deployment in place. This simply means that when a pull request is merged into the main project, the project is immediately and automatically deployed. If the change is good enough to be accepted into the project, it is also good enough to be live on the documentation site, helping your readers. Typically, continuous deployment is set up with either a separate automation server, such as Jenkins, or Git Hooks. Either way, the text-based markup is combined with the Docs as Code platform (usually a static site generator such as Hugo or Sphinx) to produce the documentation website, which is then deployed.
The same automation can be used before deployment to add some excellent checks to the pull requests before they are merged. On a coding project, it's common to run code linters, tests, and other quality checks that a machine can do itself. Documentation projects can get the same treatment, with tools like Vale to do prose linting and check for correct heading styles, spellings, and so on. It's also useful to add other tools here, such as a link checker to make sure all the links go somewhere valid.
Code tools for docs workflows
The tools known and loved by engineers are very good tools, but they are useful for all sorts of other projects too. For documentation, they contribute valuable efficiency, especially when you need your documentation to be moving at the same speed as your development teams. All the tools discussed here are open source, so you can try them for yourself, deploy them for a huge global team, or anything in between. May your docs process be as smooth as any code process.
via: https://opensource.com/article/22/10/docs-as-code
作者：Lorna Mitchell 选题：lkxed 译者：译者ID 校对：校对者ID