Consider Using Docs-as-Code(blog.doctave.com) |
Consider Using Docs-as-Code(blog.doctave.com) |
High Friction: Google Docs makes adding suggestions and comments. Opening a PR or opening a bug is so much more effort that people are much less likely to do it.
Low Visibility: When a suggestion is pending on Google Docs users reading the doc can see the pending suggestions and use them right away, even if not reviewed. When browsing code the pending changes are hard to find.
Non-Optimized: Most of the code review tools (including Git) work at the line level. (Git doesn't fundamentally care about lines but diff and merge operations do rely on lie-level diffs). Prose really needs word-level diffs to be effective.
Too simple: Formatting is very useful for docs. Markdown helps this but still falls sort of images in diagrams. Simply pasting a screenshot into a doc gets back to the High Friction concern above.
At the end of the day docs end up being much more of a collaborative experience and these issues hurt a lot more for docs then they do for code. Most organizations struggle to write docs anyways so using a tool where making improvements and additions is as simple as possible is worth more than the advantages of code. I still highly recommend reviews, but that can generally be done by leaving your edits as suggestions and asking a peer to review, comment and accept them.
However a high quality code-based-docs system has some huge advantages as well, automated checks (did you a new doc for all defined alerts), testing (run the code samples in the docs), automation (find and replace, or even just searching), portability (You can copy the source of the docs to some emergency access system in case your regular doc host dies), integration (reference functions, lines and files from your source) and others.
I would love to see docs-as-code get better but our tooling isn't ready for it yet in my opinion.
Could be useful to know how Doctave differs from Jekyll, Hugo, etc.