Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

πŸ“ƒ A curated and up-to-date list of resources on software documentation templates, tools, guides, examples, etc.

License

Notifications You must be signed in to change notification settings

pengqun/awesome-documentation

Repository files navigation

Awesome Documentation Awesome Lint

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: πŸ‡¨πŸ‡³ δΈ­ζ–‡

Contents

Documentation Types

User Documentation

"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

Tutorial

Step-by-step instructions to teach users how to use or implement the subject or tool.

Reference

Provides detailed information and specifications for all features and functionalities.

How-to

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.

Concept

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.

FAQ

Answers frequently asked questions to quickly resolve common issues or clarify typical misunderstandings.

In-app Documentation

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.

Others

Architectural Documentation

"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.

API Documentation

"All teams will henceforth expose their data and functionality through service interfaces." - The Bezos API Mandate

General

  • 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

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.
  • OpenAPI Generator - Generate API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3).
  • GitBook - A modern platform for creating and managing interactive API documentation from OpenAPI definitions.
  • xyd - Generate scalable API Docs from OpenAPI definitions easier.

GraphQL

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.
  • xyd - Generate scalable API Docs from GraphQL schema easier.

gRPC

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

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

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.

Code Documentation

README

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.

Comments

"Code Tells You How, Comments Tell You Why." β€” Jeff Atwood

Error Messages

Collaboration

Language-specific

  • 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
  • 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.
  • 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
    • Rustdoc - Generate documentation for Rust projects.
    • Docs.rs - An open source project to host documentation of crates for the Rust Programming Language.
  • 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 Documentation

Other Types

General Tools

Site Builder

Wiki Builder

  • 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

Knowledge Base

  • 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.
  • Docmost - An open-source collaborative wiki and documentation software. It is an open-source alternative to Confluence and Notion.

AI-powered Tools

  • Mintlify Writer - An AI-powered VS Code extension that automatically generates code documentation by highlighting code. Supports multiple programming languages and docstring formats including JSDoc, reST, NumPy, and more.
  • Readme AI - A developer tool that automatically generates comprehensive README files using repository analysis and language models. It supports multiple LLM providers, custom templates, and offline generation.
  • GitBook AI - A built-in AI assistant that helps teams quickly draft, refine, and enhance product documentation with smart, context-aware suggestions.

Checker & Formatter

  • 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.

Diagramming

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.
  • Mermaid - A diagramming and charting tool that renders Markdown-inspired text definitions to create charts.
  • PlantUML - Allows users to create diagrams using a simple syntax.
  • Lucidchart - Generate visuals automatically with AI and data imports, or build your own using intuitive diagramming tools.
  • OmniGraffle - A Mac-only diagramming tool that offers a wide range of features for creating diagrams.
  • (Chinese) Architecture Diagramming: Tools and Methodologies - It discusses the benefits of using diagrams in architecture document, and highlights some standards and best practices.

Multimedia

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.

Commercial

  • Confluence - A powerful collaboration and project management software, which is widely used for enterprise documentation management.
  • 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.

More Topics

Communities

  • 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.

Examples

Formats

  • Converters
    • Pandoc - A universal document converter, which can convert files from one markup format into another.
    • Mammoth - Convert Word documents (.docx files) to HTML.
  • Markdown - A lightweight markup language for creating formatted text using a plain-text editor.
    • MarkText - A simple and elegant markdown editor, available for Linux, macOS and Windows.
    • Glow - A terminal based markdown reader, which can be used to read documentation directly on the command line.
  • 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.

Guidelines

Books

Courses

DocOps

Localization

Accessibility

SEO

Contributing

Please feel invited to do any contribution.

AltStyle γ«γ‚ˆγ£γ¦ε€‰ζ›γ•γ‚ŒγŸγƒšγƒΌγ‚Έ (->γ‚ͺγƒͺγ‚ΈγƒŠγƒ«) /