GoKawiilThe palest ink is more reliable than the most powerful memory. – Chinese proverb
AI changes the game when it comes to having all your docs in your repository: it's never been that easy to keep them up to date!
I've always been a fan of having documentation living alongside the code:
Version control : just like code, documentation evolve. Why use a different versioning control system when you're already using git? Especially when multiple people are changing docs at the same time, with potentially conflicting changes.
: just like code, documentation evolve. Why use a different versioning control system when you're already using git? Especially when multiple people are changing docs at the same time, with potentially conflicting changes. Proximity with code : e.g., rg or grep will yield code and documentation results, making it much easier to keep it up to date.
: e.g., or will yield code and documentation results, making it much easier to keep it up to date. Formal approval : in the spirit of documentation-driven development, starting with a review of documentation updates help understand the final product/API. (For active collaboration other tools, e.g., Google Docs still provide a superior UX).
: in the spirit of documentation-driven development, starting with a review of documentation updates help understand the final product/API. (For active collaboration other tools, e.g., Google Docs still provide a superior UX). Automatic generation : when using a different system for hosting the docs (Google Docs, Confluence, Notion, etc.), it's quite laborious to copy-paste APIs and example code. There are many tools (e.g., Sphinx's autodoc, jsdoc, javadoc, docusaurus) that can generate API docs directly from the code.
: when using a different system for hosting the docs (Google Docs, Confluence, Notion, etc.), it's quite laborious to copy-paste APIs and example code. There are many tools (e.g., Sphinx's autodoc, jsdoc, javadoc, docusaurus) that can generate API docs directly from the code. Testing : static code examples in documentation are a good start, but it's even better when they're tested, which you can do when running code examples in docs is part of your continuous integration process. See Python's doctest for example. In a way, the documentation is the spec.
: static code examples in documentation are a good start, but it's even better when they're tested, which you can do when running code examples in docs is part of your continuous integration process. See Python's doctest for example. In a way, the documentation is the spec. Efficient editing: you benefit from all your text editor tools, and can script mass-changes.
We will be spending more time writing docs
... continue reading