Docs as Code: The Missing Manual¶
Description
Treating docs as code, an approach that more and more teams and companies are moving toward, involves more than putting the two together in a repo. We discuss some of the details that often get lost in as dev and docs learn to work together in new ways. Because if all we do is put doc files next to code files in source control, or use parts of the same workflow for code and docs, we're still isolating docs as a separate sort of responsibility, free from the obligations of systematic review and testing without which code would never be accepted into production.
Some missing parts of this newer approach to documentation workflow that we'll discuss include:
- Outlining a documentation lifecycle that describes how material moves from initial draft to final production, to help people unfamiliar with documentation development understand better how to efficiently manage documentation review and testing.
- Mapping GitHub workflow clearly to documentation workflow. This can help writers and editors understand better just how to use GitHub effectively, and equally important how it can help other contributors (notably programmers) understand the parts of the writer workflow that can be lost when docs move next to code.
- Creating an information architecture. Words need structure to provide meaning, usability, and discoverability. A strong content architecture provides logical places for adding new content, especially for doc projects at scale.
- Developing and enforcing a style guide: terminology, voice, tone. These things make the difference between words that users might understand, and documentation that can truly assist.
- Reviewing and line/copy editing. Because you wouldn't do any less for code, right?
- Conference: Write the Docs EU
- Year: 2016
About the speaker
Margaret Eker
