documentation.md

Documentation

Use Docusaurus for any custom documentation I need to write. Markdoc & nbdoc look nice too.

React Docs is a great example of what great docs are. I love their illustrations.

Examples of nice docs

• Linear Guide
• PostHog Docs
• React Docs
• Netlify Docs
• Vue Docs (Code)
• Fly Docs (Code)
• Hoppscotch Docs (Code)
• Next MDX
• Algolia Docs
• Cloudflare Workers (Code) (Article)
• Cloudflare Docs - Nice overview page. (Code)
• TSDX
• Meilisearch Docs (Code)
• Parcel 2 docs (Code)
• Shields.io readme - Clear instructions on how to start working on the project, contributing guidelines pointing to a tutorial, coding guidelines and even a high-level code walkthrough.
• inDinero Help Center in Notion - Easy example of doing help/docs for company in Notion.
• Formik Docs - NextJS + Notion + TailwindCSS + AlgoliaSearch.
• Monzo
• Expo
• Apollo - Lovely search.
• Prolens nice ASCII diagrams
• Rome Toolchain - Nice sidebar with table of contents + search.
• PlanetScale Docs (Code)
• Datadog Docs (Code)
• Strapi Docs (Code)
• Increase API Reference
• Stacks Docs (Code)
• Nebula Docs

Notes

• Top two mistakes in documentation:
  1. Assuming people know everything
  2. Assuming people are stupid
• If asked a question twice, respond the 3rd time with a URL.
• When done right your documentation is also part of your support, marketing, and even sales.
• Documentation and processes are super important -- don't go for too long without documenting everything -- even at the expense of it being half-baked, and this should be the task of many people are your company. It will save everyone time in the long run.
• Your company has a poor documentation culture. Things are slow because people don’t know how things works. Managers start micromanaging because work is slow. Leadership issues mandates. No one likes mandates, but that isn’t the problem. It was poor communication the whole time.
• Building something isn't very useful if you don't take the time to explain it to people.
• Every policy or process doc I write now has a section called “Reasons to Revisit.” It is essentially a reverse success criteria. Rather than a short list of things I would expect to see if the policy was successful.
• Better docs tips: onboarding a core engineer, conducting user research, building conceptual visualizations with a dedicated product team throughout

Links

• Beautiful Docs - Pointers to useful, well-written, and otherwise beautiful documentation.
• Ask HN: Is there a better way to document complex software architectures? (2018) -
• Docusaurus - Easy to maintain open source documentation websites.
• Write the Docs - Global community of people who care about documentation. (Code)
• Documentation Guide - Gathers the collective wisdom of the Write the Docs community around best practices for creating software documentation.
• Lobsters: What does your company use for documentation? (2019)
• GitDocs - Easy to use, SEO-friendly, beautiful documentation that lives in your git repo.
• A Rubric for Open Source Documentation (2019)
• Ask HN: What is key to good technical documentation? (2019)
• Slab - Simple, scalable wiki that knocks down silos. (HN)
• How to remove condescending language from documentation (2019)
• Rich docs with Storybook MDX (2019)
• mdBook - Create book from markdown files. Like Gitbook but implemented in Rust.
• mdbook-generate-summary - Tool to generate an mdBook SUMMARY.md page.
• The Knowledge: Towards a Culture of Engineering Documentation
• We Need a New Document Markup Language - Here is Why (2019)
• Devhints - TL;DR for documentation. (Code)
• Metadoc - Online documentation platform where developers collaborate and learn from shared inline notes, bookmarks and comments.
• Ask HN: How does your company keep track of lessons learned? (2020)
• Technical Writing Courses for Engineers by Google (HN)
• Almanac - Workspace for your team's knowledge.
• MkDocs - Project documentation with Markdown.
• Docz - Makes it easy to write and publish beautiful interactive documentation for your code. (Web)
• gatsby-starter-docz - Gatsby starter with Docz and a blog for your documentation.
• Stripe Docs interactive example
• Artifact - Simple, linkable and trackable design documentation tool for everybody.
• Gatsby theme for your knowledge base or help center
• Read the Docs - Spend your time on writing high quality documentation, not on the tools to make your documentation work.
• cheatset - Generate cheat sheets for Dash.
• Doctocat - Gatsby theme for creating Primer documentation sites. (Code)
• Docup - Single JavaScript file that fetches Markdown file and renders it as a beautiful one-page documentation. (Code)
• RFCs and asynchronous-first culture (2020)
• Today’s Javascript, from an outsider’s perspective (2020) (Lobsters) (HN)
• What could be improved in the documentation process? (2020)
• Add a “contrib” directory to your projects (2020) (Lobsters)
• Nextra - Next.js based documentation site generator. 0 line of code needed, just write Markdown. (Docs) (Tweet)
• Writing inclusive documentation
• Google developer documentation style guide
• ReadMe - Beautiful, personalized, interactive docs.
• Favorite docs collection (and why) (2020)
• Ask HN: How do you learn new libraries without much documentation? (2020)
• Design Docs at Google (2020) (HN)
• Outline - Open, extensible, wiki for your team built using React and Node.js (Code)
• Why Write ADRs (2020) (HN)
• I Love MDN, or the cult of the free in action (2020) (HN)
• Architecture decision record (ADR) - ADR is document that captures an important architectural decision made along with its context and consequences.
• docsify - Magical documentation site generator. (Code) (Awesome)
• Just the Docs - Modern, high customizable, responsive Jekyll theme for documention with built-in search.
• vite-plugin-react-page - Vite plugin for React. It is very suitable for document site and React UI development environment.
• The Documentation Compendium - Various templates & tips on writing high-quality documentation that people want to read.
• Smooth Doc - Ready to use documentation theme for Gatsby.
• Furo - Clean customizable theme for Sphinx.
• MyST - Fully-functional markdown flavor and parser for Sphinx. (Code)
• DocuAPI - Beautiful multilingual API documentation theme for Hugo.
• Make a readme - Explains what a readme is, what the benefits are, and what makes for a good readme. (Code)
• On Apple's Piss-Poor Documentation (2020) (HN)
• Tips about making quality engineering documentation (2020)
• Pycco - Literate-style documentation generator.
• How to write good documentation (2020)
• The career-changing art of reading the docs (2021)
• DocSearch - Search made for documentation by Algolia. (Code) (Configs)
• Framework for Writing Better Documentation (HN) (HN)
• Improving Usability by Writing Documentation (2021)
• What nobody tells you about documentation (2017)
• paradoc - One Click Docs.
• Ask HN: How to write documentation for a medium size engineering org? (2021)
• Dokz - Effortless documentation with Next.js and MDX. (Web)
• Ask HN: How Do You Write Documentation (2021)
• Ask HN: How do I improve boring README page? (2021)
• Docuowl - Generates a static single-page documentation from Markdown files.
• The Grand Unified Theory of Documentation (HN) (Code)
• Writing Docs at Amazon (2019)
• Word usage guidance and alternative terms (HN)
• Why programmers don’t write documentation (2021) (HN)
• Docusaurus 2 Beta (2021) (HN)
• Common Documentation Mistakes and How to Avoid Them (2021)
• The case for Continuous Documentation (2021) (HN)
• Archbee - Documentation Tool for your Team and Product.
• Explaining Code using ASCII Art (2019) (HN)
• Useful and useless code comments (2021) (HN)
• Ask HN: What software do you use to gather requirements? (2021)
• Bikeshed - Preprocessor for anyone writing specifications that converts source files into actual specs.
• Library - Collaborative documentation site, powered by Google Docs. (Code)
• Making world-class docs takes effort (2021) (Lobsters)
• Writing Well-Documented Code - Learn from Examples (2021) (HN)
• Writing class documentation (2021)
• When does your team write release notes? (2021)
• Writing Engineering Guidelines
• Docs for Developers: An Engineer’s Field Guide to Technical Writing Book
• SveltePress - Documentation tool built on top of SvelteKit. (Code)
• Q&A: How We Document Software Projects (2020)
• Material for MkDocs - Technical documentation that just works. (Web)
• Almanac for Public Documentation - Let anyone suggest changes to technical & community docs.
• Computers can be understood (2020)
• Doctave - Batteries-included developer documentation site generator.
• Documentation could be so much better (2021)
• Best developer doc examples (2021)
• Documenting Architecture Decisions (2011)
• Ask HN: What are you using for public documentation these days? (2021)
• How to Comment Your Code (2021)
• Fundoc - Language agnostic documentation generator. Written in Rust.
• Best practices for writing code comments (2021) (HN)
• Template for the Read the Docs tutorial
• EventCatalog - Discover, Explore and Document your Event Driven Architectures. (Code)
• Text-Runner - Agile documentation tool that helps create living end-user readable documentation.
• Writing better release notes
• Keeping documentation in sync with source code (2022) (HN)
• Tagref - Helps you maintain cross-references in your code.
• What are you using to write your company handbook?
• docsify-cli - Magical documentation generator.
• My favorite things about working at companies with a culture of writing (HN)
• Ask HN: How do you manage your companies knowledge base? (2022)
• HonKit - Building beautiful books using Markdown - Fork of GitBook.
• The Death of Process (2022) (HN)
• Low-Effort, High-Value Documentation (2021)
• Organisational Scaling Knowledge Management Tips (2022)
• docs.page - Create an instant Open Source docs page with zero configuration. (Code)
• docs-scraper - Scrape documentation into Meilisearch.
• VuePress theme - Gitbook inspired
• nbdoc: Authoring With Notebooks (Code) (Tweet)
• doc-builder - Package used to build the documentation of our Hugging Face repos.
• Vale - Static documentation generator, designed for speed, simplicity and readability.
• Paradox - Markdown documentation tool for software projects.
• Vercel has nice changelog
• StrictDoc - Software for writing technical requirements specifications.
• SourceDocs - Generate Markdown documentation from source code.
• doctree - First-class library docs tool for every language. (Video) (Tweet)
• Squeak - Q&A widget for your docs.
• changelogen - Beautiful Changelogs using Conventional Commits.
• docs-searchbar.js - Front-end search bar for documentation with Meilisearch.
• Spacebook - Create fast and simple documentation to explain almost anything. Uses Eleventy, Tailwind 2.0, and Alpine JS with an optional Netlify CMS. (Code)
• Markdoc - Powerful, flexible, Markdown-based authoring framework. By Stripe. (Code) (HN) (Tweet) (Interactive Docs with Markdoc) (HN)
• How to Make a Docs Site: Shortcuts for Busy Devs
• How do you create documentation websites today? (2022)
• What Fields - Way to quickly write & share documentation for anything (API, database etc).
• Useful resources for folks building docs in open source
• Mintlify - Continuous Documentation Platform. (GitHub) (Writer) (Writer Code) (HN)
• Write documentation first, then build (HN)
• Docco - Quick-and-dirty, hundred-line-long, literate-programming-style documentation generator.
• Rain of Change - Contentrain NuxtJS and TailwindCSS Changelog template.
• Distributed - Build a knowledge base, ask questions and stay in sync with your team all while doing it asynchronously. (Code)
• How do do docs for your projects?
• Identifying content gaps in our documentation
• An engineer’s tips for writing documentation devs love (2022) (HN)
• Keep calm and use the runbook (HN)
• Typograms - Markdown-like renderer for ASCII diagrams. (HN)
• GoAT - Render ASCII art as SVG diagrams.
• Offline-docs - Collection of scripts to build offline documentation for your favorite frameworks/libraries.
• Search less, browse more (Lobsters)
• Ask HN: Whats the best SDK documentation you’ve ever read, and why? (2022)
• parse-changelog - Simple changelog parser, written in Rust.
• I’m a Productive Programmer with a Memory of a Fruit Fly
• What’s your favorite go to documentation tool for building team knowledge base (2022)