When docs as code is a big success, this is why
There are situations where the Docs as Code approach is unarguably the best. The primary example is when engineers maintain an OpenAPI spec that becomes HTML documentation.
In that case, it works because when engineers create a new property in the code, nobody else knows what the property is for, and the most sensible and efficient approach is for the engineer to write the description, followed by some kind of review by a technical writer. It follows naturally to provide editing tools that are familiar and comfortable for the engineers.
If the process was badly configured before the implementation of Docs as Code the results can be dramatic: immediate positive feedback from customers, less frustration for the authors, and the general smoothing of the process.
In other situations, applying the same methodology doesn't provide nearly the same breakthrough results.
Here is the key: The best predictor of effectiveness is knowing in the beginning that the changes will help end users. A lot.
In the case of OAS3 specs and other reference, material that's written by engineers is more accurate and complete, and those are the factors that count the most with reference documentation. The reduction in difficulty and frustration for customers is a huge benefit in proportion to the amount of work invested.
If a particular practice doesn't result in a benefit noticeable to the end user of your software and isn't making work easier for the authors (whether engineers or technical writers), then that practice most likely isn't needed.
For example:
* Do source files need to be stored with the code, if engineers don't do the writing?
* Do you need to apply code freeze to the documentation on the same day that code freeze happens for the code, if documentation isn't inserted into the application? Would a few more days help to accommodate last-minute changes in the code?
* Is it necessary for everyone to use the same editing tools and markup? If certain tools and processes make sense for the engineer-written documentation, use them, but don't assume that they also work for technical writers working on other documentation.
Up next: Q&A with Anne Gentle, author of “DOCS LIKE CODE.”