A curated and up-to-date list of resources on software documentation templates, tools, guides & examples.
Software documentation is critical to ensuring clarity and efficiency throughout the development process by facilitating better understanding and collaboration among team members. However, for a variety of reasons, the creation and maintenance of documentation has often been mismanaged, resulting in inefficiency, inconsistency, and poor quality.
This list aims to help by providing you with out-of-the-box templates and practical tools to maximize efficiency, insightful guides and established standards to ensure consistency, and real-world documents to serve as examples.
Translations available in: π¨π³ δΈζ
"It doesn't matter how good your product is, because if its documentation is not good enough, people will not use it." - The Documentation System
Step-by-step instructions to teach users how to use or implement the subject or tool.
- Tutorial - Lean how to write good tutorials from The Documentation System.
- Tutorial template - Open-source template provided by The Good Docs Project.
- Writing a perfect technical tutorial - How to start creating tutorials, gather feedback, and the next steps once the tutorial is published.
- Example: Build your first Astro Blog - A well-structured and good-looking tutorial that covers Astro's key features by building a fully-functioning blog, from zero to full launch.
Provides detailed information and specifications for all features and functionalities.
- Reference guides - Lean how to write good reference guides from The Documentation System.
- Reference template - Open-source template provided by The Good Docs Project.
- SDK Reference Manuals: A flow-based approach - Give users of SDK reference docs a quick, enjoyable, user-oriented experience.
Offers practical steps to accomplish specific tasks or solve common problems.
- How-to guides - Learn how to write good how-to guides from The Documentation System.
- How-to template - Open-source template provided by The Good Docs Project.
Explains the fundamental ideas and theories behind the topic.
- Concept template - Open-source template provided by The Good Docs Project.
- Explanation - Learn how to write a good explanation from The Documentation System.
Answers frequently asked questions to quickly resolve common issues or clarify typical misunderstandings.
- The Facts About FAQs - Explore various questions we might frequently ask ourselves about FAQs.
Assist users in understanding and navigating the features and functionalities of the app directly from within its interface.
- Driver.js - A light-weight, no-dependency, vanilla JavaScript engine to drive the user's focus across the page.
- Shepherd - Guide your users through a tour of your app.
- Installation template - Open-source template provided by The Good Docs Project.
- Troubleshooting template - Open-source template provided by The Good Docs Project.
- Terminology system guide template - Open-source template provided by The Good Docs Project.
- Release Notes template - Open-source template provided by The Good Docs Project.
- The Power of Empathy in Support Documentation: A 5-Step Guide - Apply empathy and iteration to customer support documentation projects.
"Architecture is about the important stuff. Whatever that is." β Ralph Johnson
-
arc42 - Proven,Β practical and pragmatic template forΒ documentation and communication of software and system architectures.
- Template Download - The arc42 template in various formats, including docx, asciidoc, markdown, latex, rst, html, Confluence, etc.
- Example: HTML Sanity Checker - Verbose example for the documentation of a Gradle plugin, created by Dr. Gernot Starke.
- Example: biking - A real world example for a bike activity tracker, created by Michael Simons.
- Example: arc42 + C4 model - Shows how to use arc42 in combination with the C4 model with the Documentation as Code technique.
- docToolchain - An implementation of the docs-as-code approach for software architecture, which use arc42 as template.
- The Ultimate Guide To Software Architecture Documentation - Write, structure, visualize and manage software architecture documentation in a lean way using appropriate documentation tools, including arc42.
-
C4 model - The C4 model for visualizing software architecture using Context, Containers, Components, and Code.
- c4-draw.io - A C4 Modelling plugin for draw.io, which provides C4 Notation Elements in draw.io.
- C4-PlantUML - Includes macros, stereotypes, and other goodies (like VSCode Snippets) for creating C4 diagrams with PlantUML.
- C4 Diagrams | Mermaid - Mermaid's C4 diagram syntax is compatible with plantUML.
- Structurizr - C4 models as code - visualise and document your software architecture with the C4 model.
- C4-Builder - A lightweight Node.js cli tool for building, maintaining and sharing a software architecture project using only text.
- C4Sharp - A .net library for building diagrams as code, based on C4 Model.
- Goa Design - Model - Create your software architecture models and diagrams in Go. The Model DSL is implemented in Go and follows the C4 Model.
-
Log4brains - Log Architecture Decision Records (ADR) right from your IDE and to publish them automatically as a static website.
-
Design Docs at Google - Overview of how software design docs are used and written at Google.
"All teams will henceforth expose their data and functionality through service interfaces." - The Bezos API Mandate
- API Reference template - Open-source template provided by The Good Docs Project.
- Slate - Beautiful static documentation for your API.
- Widdershins - OpenAPI / Swagger / AsyncAPI / Semoasa definition to Slate / ReSlate compatible markdown.
- DevDocs - Combines multiple developer documentations in a clean and organized web UI with instant search, offline support, mobile version, dark theme, keyboard shortcuts, and more.
- Zeal - Offline documentation browser inspired by Dash.
- apiDoc - RESTful web API Documentation Generator.
OpenAPI Specification defines a standard, language-agnostic interface to HTTP APIs. An OpenAPI definition can then be used by documentation generation tools to display the API.
- Swagger UI - Dynamically generate beautiful documentation from a Swagger-compliant API.
- Swagger Petstore - A sample Pet Store Server based on the OpenAPI 3.0 specification.
- Redoc - An open source tool for generating documentation from OpenAPI (formerly Swagger) definitions.
- RapiDoc - WebComponent Custom Element for OpenAPI Spec viewing.
- Fern - Generate SDKs and API documentation from OpenAPI definitions.
- Elements - Beautiful API documentation powered by OpenAPI and Markdown.
- Scalar - Generate interactive API documentations from Swagger files.
GraphQL is a query language for APIs, which provides a complete and understandable description of the data in your API.
- GitHub GraphQL API documentation - A great real world example of GraphQL API from GitHub.
- SpectaQL - A Node.js library that generates static documentation for a GraphQL schema.
- GraphQLDocs - Ruby library and CLI for easily generating beautiful documentation from your GraphQL schema.
- Magidoc - A a JavaScript library that auto-generates static documentation from any GraphQL schema.
gRPC is a modern open source high performance Remote Procedure Call (RPC) framework.
- protoc-gen-doc - Generate HTML, JSON, DocBook, and Markdown documentation from comments in your .proto files.
- Example - A sample HTML documentation generated by protoc-gen-doc.
- Sabledocs - A simple static documentation generator for Protobuf and gRPC contracts.
- Example - A sample documentation created with sabledocs, from parts of the Protobuf contracts of the Google Cloud SDK.
AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format, which can also be used to generate API documents.
- Async API Generator - Use AsyncAPI definition to generate literally anything, including Markdown documentation and HTML documentation.
- AsyncAPI React Component - Rendering documentation from your specification in real-time in the browser.
- Petstore Kafka - A functional example for describing with AsyncAPI and OpenAPI.
RAML Specification provides mechanisms for defining practically-RESTful APIs, creating client/server source code, and comprehensively documenting the APIs for users.
- API Console - An interactive REST console based on RAML/OAS files.
- RAML to HTML - A simple RAML to HTML documentation generator, written for Node.js, with theme support.
- World Music API - A live example using RAML to HTML documentation generator.
README files are a staple of any code project. They provide the first introduction to a new codebase and help you share important project details with collaborators.
- Best-README-Template - An awesome README template to jumpstart your projects.
- Awesome README - A curated list of awesome READMEs, including examples, articles and tools.
- README template - Open-source template provided by The Good Docs Project.
- readme.so - An online drag-and-drop editor to easily build READMEs.
βCode Tells You How, Comments Tell You Why.β β Jeff Atwood
- Best practices for writing code comments - 9 rules to help you write better comments, providing examples and explaining how and when to apply them.
- The Engineer's Guide to Writing Meaningful Code Comments - Covers types of comments, when and how to write code comments, some best practices, and when not to write them.
- NERD Commenter - Vim plugin for intensely nerdy commenting powers.
- 101 to 404s: How to write great error messages - Even the shortest error message can evoke far stronger, negative emotions in your end users than the majority of your documentation.
- CONTRIBUTING template - Open-source template provided by The Good Docs Project.
- Code Of Conduct template - Open-source template provided by The Good Docs Project.
- Style guide template - Open-source template provided by The Good Docs Project.
- License
- JavaScript
- JSDoc - An API documentation generator for JavaScript.
- documentation.js - The documentation system for modern JavaScript.
- Docz - Write and publish beautiful interactive documentation for your code.
- Storybook - A frontend workshop made for UI development, testing, and documentation.
- TypeScript
- TSDoc - A doc comment standard for TypeScript.
- Python
- Docstring Conventions - This PEP documents the semantics and conventions associated with Python docstrings.
- Comments and Docstrings - From Google Python Style Guide.
- Documenting Python Code: A Complete Guide - Covering differences between commenting and documenting, use of docstrings, and guidelines for documenting Python projects.
- PHP
- phpDocumentor - The de-facto documentation tool for PHP projects, offering a robust solution for generating comprehensive documentation effortlessly.
- C#
- Docfx - Static site generator for .NET API documentation.
- C++
- Doxygen - The de facto standard tool for generating documentation from annotated C++ sources.
- Java
- JavaDoc - A documentation generator created by Sun Microsystems for the Java language (now owned by Oracle Corporation) for generating API documentation in HTML format from Java source code.
- Maven Javadoc Plugin - Uses the Javadoc tool to generate javadocs for the specified project.
- javadoc.io - A free service that indexes and serves JavaDoc for Maven Central.
- JavaDoc - A documentation generator created by Sun Microsystems for the Java language (now owned by Oracle Corporation) for generating API documentation in HTML format from Java source code.
- Kotlin
- Dokka - An API documentation engine for Kotlin.
- Go
- Go Doc Comments - Extract documentation from Go source code.
- Swag - Cconverts Go annotations to Swagger Documentation 2.0.
- Rust
- Ruby
- TomDoc for Ruby - A code documentation specification that helps you write precise documentation that is nice to read in plain text, yet structured enough to be automatically extracted and processed by a machine.
- Perl
- perlpod - The Plain Old Documentation format - a simple-to-use markup language used for writing documentation for Perl, Perl programs, and Perl modules.
- SQL
- SchemaSpy - Document your database simply and easily.
- CSS
- Test Plans
- IEEE Test Plan Template - IEEE 829 templates in HTML5 and Markdown formats.
- SONiC Test Plan Template - A test plan template from Software for Open Networking in the Cloud (SONiC).
- Writing Test Plan Items | VS Code - A guide for writing Test Plan Item (TPI) for VS Code project.
- Performance Test Plan Document - A free .docx template for performance test plan from PerfMatrix.
- Test Cases
- TestCases and Templates for Manual Software Testing - General Test Cases for performing Manual Testing and API Testing on the Web/Mobile application.
- Test Case Template (Download Sample Excel) - A free test case template from Guru99, with both Excel and Word formats.
- Test Case Template with Examples: Free Excel & Word Sample for Download - A free test case template from Katalon, with guidelines and direct download links.
- Test Report
- Bug report template - Open-source template provided by The Good Docs Project.
- Performance Test Report Template - A free .docx template for performance test report from PerfMatrix.
- Performance Testing Results Report: How to Write It (with Example) - A guide on performance testing report, including why, how and a real world example.
- A Step-by-Step Guide to Creating a Powerful Performance Summary Report - Discuss the best practices for creating a performance test summary report and the key components that should be included in it, with a full example.
- Project Requirements Documentation (PRD)
- PRD: Product Requirements Doc templates - A bunch of PRD templates from Notion, both free and paid.
- Product Templates: Product Requirements Document (PRD) - Free PRD Templates from Product School.
- PRD templates for product managers - PRD templated from Aha! software.
- RFC (Request for Comment)
- Docusaurus
- A project for building, deploying, and maintaining open source project websites easily.
- Docsify
- A magical documentation site generator.
- MkDocs
- A fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
- Material for MkDocs
- A powerful documentation framework on top of MkDocs.
- Material for MkDocs
- mdBook
- Create book from markdown files. Like Gitbook but implemented in Rust.
- Sphinx
- Make it easy to create intelligent and beautiful documentation.
- Read the Docs - Hosts documentation for the open source community, which supports Sphinx docs written with reStructuredText.
- Markdoc - A Markdown-based syntax and toolchain for creating custom documentation sites and experiences.
- Starlight
- Build beautiful, accessible, high-performance documentation websites with Astro.
- Docco
- A quick-and-dirty, hundred-line-long, literate-programming-style documentation generator.
- bookdown
- Authoring Books and Technical Documents with R Markdown.
- Docus
- Create document-driven websites with Vue & Markdown.
- Doctave
- A batteries-included developer documentation site generator.
- Wiki.js - A modern and powerful wiki app built on Node.js.
- MediaWiki - A free and open-source wiki software package written in PHP. It serves as the platform for Wikipedia and the other Wikimedia projects.
- DokuWiki - A simple to use and highly versatile Open Source wiki software that doesn't require a database.
- Gollum - A simple wiki system built on top of Git.
- VimWiki - A a personal wiki for Vim, which can be used to write documentation.
- GitHub Wiki
- Awesome GitHub Wikis - A curated list of awesome GitHub Wikis, including examples, tips and tricks.
- Federated Wiki
- The Federated Wiki - Use federation to ease sharing, by Ward Cunningham.
- Node.js server version - Federated Wiki node server as npm package.
- Documize - Modern Confluence alternative designed for internal & external docs.
- Trilium Notes - A hierarchical note taking application with focus on building large personal knowledge bases.
- Seafile - High performance file syncing and sharing, with also Markdown WYSIWYG editing, Wiki, file label and other knowledge management features.
- Logseq - A privacy-first, open-source platform for knowledge management and collaboration.
- MrDoc - An online document system suitable for individuals and small teams to manage documents, wiki, knowledge and notes.
- AFFiNE - A next-gen knowledge base that brings planning, sorting and creating all together.
- LanguageTool - Style and Grammar Checker for 25+ Languages.
- Spellcheck GitHub Actions - A GitHub Action that spell checks Python, Markdown, and Text files.
- TeXtidote - A correction tool for LaTeX documents and other formats.
- alex - Catch insensitive, inconsiderate writing.
- Lychee - Finds broken URLs and mail addresses inside Markdown, HTML, reStructuredText, websites and more.
- linkinator - A super simple site crawler and broken link checker.
- Readability checker - Score your writing based on the Flesch reading ease scale, which looks at how long your words and sentences are.
- Capitalize My Title - An easy, smart title capitalization tool that uses title capitalization rules published by leading professional organizations to ensure your titles and headlines are capitalized correctly.
- CasePolice - Scan all your source files and fix the cases of known names.
- Tables Generator - Generate tables in HTML, Markdown, Latex, MediaWiki, etc.
One diagram is usually worth more than a thousand words.
- Excalidraw - An open source virtual hand-drawn style whiteboard for sketching hand-drawn like diagrams.
- draw.io (Open Source) - A JavaScript, client-side editor for general diagramming.
- (Chinese) Architecture Diagramming: Tools and Methodologies - It discusses the benefits of using diagrams in architecture document, and highlights some standards and best practices.
Documentation can be more than just plain texts and static pictures.
-
Screen Recorder
- Screenity - The free and privacy-friendly screen recorder with no limits.
- Kap - An open-source screen recorder built with web technology.
- rrweb - A tool for recording and replaying users' interactions on the web.
- ScreenToGif - Record a selected area of your screen, edit and save it as a gif or video.
- Peek - Simple animated GIF screen recorder with an easy to use interface.
- Flameshot - Powerful yet simple to use screenshot software.
-
Audio Recorder
- Tenacity - An easy-to-use, privacy-friendly, FLOSS, cross-platform multi-track audio editor for Windows, macOS, Linux, and other operating systems.
-
Terminal Recorder
- asciinema - A command-line tool for recording terminal sessions.
- Terminalizer - Record your terminal and generate animated gif images or share a web player.
-
Animation Builder
- Animockup - A web-based tool that helps you create animated mockups for your product teasers.
-
Presentation Tools
- Slidev - Presentation slides for developers.
- reveal.js - Open source HTML presentation framework.
- carbon - Create and share beautiful images of your source code.
- Code Hike - Helps you create a superior code reading experience, whether you are writing blog posts, documentation, tutorials, coding videos, or any type of technical content.
-
Free Icons & Images
- Unsplash - Beautiful, free images and photos that you can download and use for any project.
- Illustrations | Popsy - Free vector illustrations for Notion and Popsy websites.
- KindPng - Explore millions of transparent png image for personal and non-commercial use.
- Confluence - A powerful collaboration and project management software, which is widely used for enterprise documentation management.
- Confluence in a Docker container - Atlassian Confluence wrapped in a Docker image.
- Writerside | JetBrains - The most powerful development environment β now adapted for writing documentation.
- Project documentation |Β Slite - Brings your scattered project documents into one place: from project plans, to specs and process documentation.
- Swimm document - Code documentation for developer productivity, including AI support to improve readability.
- Kapa.ai - Generate an LLM-powered chatbot that answers developer questions automatically and helps you find gaps in your docs.
- Write the Docs - A global community of people who care about documentation.
- The Good Docs Project - Educates and empowers people to create high-quality documentation.
- Technical Writing | Reddit - For people who take the unbelievably complicated things that scientists and engineers devise and make it understandable for non-technical people.
- Beautiful Docs - Pointers to useful, well-written, and otherwise beautiful documentation.
- Awesome Open Source Documents - A curated list of awesome open source or open source licensed documents, guides, books.
- Awesome Documentation | vipulgupta2048 - A curated list of awesome real-life documentation examples.
- 9 Great API and Developer Documentation Examples - Cover common areas of documentation, plus some areas you might not typically see called docs.
- Converters
- Markdown - A lightweight markup language for creating formatted text using a plain-text editor.
- AsciiDoc - A plain text markup language for writing technical content.
- Asciidoctor - A fast, open source, Ruby-based text processor for parsing AsciiDoc and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.
- Antora - A modular documentation site generator that helps you organize and publish content written in AsciiDoc to the web.
- reStructuredText - The default plaintext markup language used by Sphinx.
- DocBook - An XML schema for writing books and manuals about technical subjects.
- LaTeX - A document preparation system.
- Style Guides - Collections of style guides from Write the Docs community.
- Google developer documentation style guide - Provides editorial guidelines for writing clear and consistent Google-related developer documentation.
- Microsoft Writing Style Guide - If you write about computer technology, this guide is for you.
- Editorial guidelines for Apple - Provides guidelines to help maintain a consistent voice in Apple materials, including documentation.
- GitHub Docs Style guide - Make sure GitHub's documentation stays consistent and follows clear patterns that our readers can understand.
- Red Hat Technical Writing Style Guide - Includes everyday punctuation and grammar, common mistakes to avoid, strategies for translation and global audiences, and a word usage dictionary.
- How to Write Good Documentation | UC Berkeley - Help you to prepare your code for publishing through writing a good documentation.
- Series: Writing Great Documentation - A series of articles laying out the tools, tips, and techniques author learned over the years he've spent helping to write Django's docs.
- Command Line Interface Guidelines - An open-source guide covering CLI help text and documentation.
- Docs for Developers: An Engineer's Field Guide to Technical Writing - Teaches you the craft of documentation for each step in the software development lifecycle.
- Technical Documentation and Process - Provide the background and structure to help you document your projects more effectively.
- Crafting Docs for Success : An End-to-End Approach to Developer Documentation - Provide an easy to follow blueprint for building successful developer documentation by using the award winning platformOS developer portal as inspiration.
- Docs-as-Ecosystem: The Community Approach to Engineering Documentation - Teaches readers how mastering the docs-as-code ecosystem empowers communities to understand better their favorite products and Open-Source (OSS) technologies better.
- Documenting Software Architectures: Views and Beyond, Second Edition - Provides the most complete and current guidance, independent of language or notation, on how to capture an architecture in a commonly understandable form.
- Communication Patterns - Shows you how to create documentation and diagrams that actually get the message across to the different audiences you'll face.
- Living Documentation: Continuous Knowledge Sharing by Design, First Edition - Use an Approach Inspired by Domain-Driven Design to Build Documentation That Evolves to Maximize Value Throughout Your Development Lifecycle.
- Communicating Design: Developing Web Site Documentation for Design and Planning, Second Edition - Shows you how to make the documentation you're required to provide into the most efficient communications tool possible.
- Information Development: Managing Your Documentation Projects, Portfolio, and People - A completely new look at best practices for all phases of the document development lifecycle.
- Technical Writing Courses for Engineers - This collection of courses and learning resources from Google aims to improve your technical documentation.
- Technical Writer HQ - Hosts popular certification courses covering different aspects of technical writing in an applicable way.
- DocOps Collection - These articles offer an introduction to the concept of DocOps.
- What is DocOps, anyway? - Awesome article from Write the Docs community.
- Docs as Code - Awesome article from Write the Docs community.
- DocOps Lab - A platform for collaboratively developing and exploring docs-as-code infrastructure, automation, workflows, etc.
- What is Continuous Documentation? The manifesto
- Shifting to Continuous Documentation as a New Approach for Code Knowledge
- Localize the Docs - Awesome video from Write the Docs community.
- Found in Translation: Lessons from a Year of Open Source Localization - Awesome video from Write the Docs community.
- Documents Accessibility - The Definitive Guide - How to make your documents meet accessibility standards.
- Website Accessibility Checker - Scan your website for free, identify accessbility issues, and get exact instructions on how to fix them.
- Color Contrast Checker - Find out whether your site meets WCAG color requirements.
- WebAIM - Web accessibility in mind.
- Pa11y - Runs accessibility tests on your doc pages via the command line or Node.js.
- Create accessible documents | UW Madison - Follow these basic steps to increase the accessibility of your Word, HTML, PowerPoint and PDF documents.
- How to do search engine optimization (SEO) for documentation projects - Explains how documentation can be optimized to appear in search results, ultimately increasing traffic to your docs.
- Search engine optimization (SEO) for documentation - SEO guide from Write the Docs community.
- Five ways to improve SEO of your technical documentation and OpenAPI references - Five ways to improve the search engine rankings of your technical docs and OpenAPI specification.
- Search Engine Optimization (SEO) Starter Guide | Google - Provides the best practices to make it easier for search engines (not just Google) to crawl, index, and understand your content.
- Search engine optimization (SEO) | Docusaurus - Show how Docusaurus as documentation site builder supports SEO in a variety of ways.
Please feel invited to do any contribution.