Skip to content

πŸ“ƒ 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

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

57 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

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.

Conecpt

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.

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.

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

  • Docusaurus GitHub Repo stars - A project for building, deploying, and maintaining open source project websites easily.
  • Docsify GitHub Repo stars - A magical documentation site generator.
  • MkDocs GitHub Repo stars - A fast, simple and downright gorgeous static site generator that's geared towards building project documentation.
  • mdBook GitHub Repo stars - Create book from markdown files. Like Gitbook but implemented in Rust.
  • Sphinx GitHub Repo stars - 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 GitHub Repo stars - Build beautiful, accessible, high-performance documentation websites with Astro.
  • Docco GitHub Repo stars - A quick-and-dirty, hundred-line-long, literate-programming-style documentation generator.
  • bookdown GitHub Repo stars - Authoring Books and Technical Documents with R Markdown.
  • Docus GitHub Repo stars - Create document-driven websites with Vue & Markdown.
  • Doctave GitHub Repo stars - A batteries-included developer documentation site generator.

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.

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

Comunities

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