Two open source projects with great documentation • John Jago
Tutorials, how-to guides, technical reference and explanation
The Ultimate Guide To Software Architecture Documentation Software architecture documentation creates a common understanding of the solution behind the system for various stakeholders
The documentation makes it possible to evaluate the software architecture from the perspective of the various stakeholders
Software architecture documentation supports team work
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:
Issue Trackers
Version Control (Git)
Plain Text Markup (Markdown, reStructuredText, Asciidoc)
Code Reviews
Automated Tests
How Stripe builds interactive docs with Markdoc
Extends Markdown with custom syntax that meets the needs of our documentation platform without sacrificing Markdown's simplicity, familiarity, or ease of use for writing prose
Requires an Express app / Javascript backend.
An Engineer's Best Tips for Writing Documentation Devs Love - The New Stack
Writers should value their readers’ time — and always try to get to the point.
Examples should always show actual real-world problems – since so many readers will be jumping straight to your code samples.
Always verify your instructions before publishing documentation.
The only thing worse than no documentation is incorrect documentation.
How do you make readable or presentable documentation?
Treat your docs as a product.