Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.
Docs as Code: The Missing Manual
by Margaret Ecker and Jennifer Rondeau
Starting a docs project, or any project is often like exploring forest, we are eager to go forward and explore but we may not have a plan.
Docs as code is not new, but there is elaboration that needs to be done to make this a bridge building that exposes the trees more (and mixes the metaphors :D).
Anne Gentle suggests that Docs as Code means:
- Web delivery
- CI for docs
- Collaboration on docs uses code systems
- CMS using code systems
To this Margaret and Jennifer add:
- Docs in a repository together, with or close to the code
- Lightweight plain text markup language
- Build to HTML using static site generators or doc generators
- Multiple stakeholders
- Iterative assumptions and an agile development model
How do we get there?
Release Planning
Doc requirements, like other components are driven by user stories. This is not a surprise and allows some scoping. In a lot of cases the assumption is that all the changes will be quick updates. However, in many cases you have a new audience, new features, or a new product or service. This assumption that all of the work is just quick updates is why you wind up at the end of the project with a huge manual or help system to write. This is a failure to scope.
Design Phase
During the design phase there needs to be additional work that resembles planning. Consider the types of docs required, content model, content type templates and deployment models.
Development Phase
Work during the development phase is going to require a doc development environment setup. It is assumed you’ve solved source formats, source storage, content models and templates, contributor collateral, and training.
Develop Content
- Research
- Outline
- Write
- Submit (commit -> automatic build -> deploy to staging)
Before this though, the proper docs development environment will allows developers to do a brain dump and give doc pieces for further elaboration by writers.
Testing
A significant gap is in testing. Code tends to write tests first. Documentation testing tends to be manual and is limited to language. Reviews are usually done manually via a PR process.
Compare these workflows:
It Is Not All Easy
No matter how many templates or models you have, the blank page is scary. We need guidelines that remind people not to be afraid of this page. This will never be what is actually built and deployed. This is particularly useful to remind developers.
Docs as code by itself doesn’t guarantee the delivery of high quality docs. But it does enable a shared vocabulary and work flow with all potential contributors. Even just this change sets us up for greater success.
The hardest part is building trust.
