Where to Start

So you wrote A Thing To Share With The World and you're wondering how to document it. Or maybe you're facing a growing codebase that's becoming a platform but doesn't have documentation. Perhaps you're a platform whose documentation is relatively incomprehensible and everyone complains about it but no one on the OSS team knows where to start fixing it. Here's a list of what to document, given the type of project.

If you're documenting a Small Tool 🛠

This project is some bridge or adapter or utility toolbelt for some highly specific use. Usually found in companies for translating file formats or analysis. Commonly found in OSS to translate between protocols or abstract the integration of multiple libraries.

You need:

• Quickstart
• API Documentation

If you're documenting a Library 📚

This project gives powers to a programmer that are novel and not part of the standard library, such as a performing a physics calculation or for drawing vector shapes on a screen given points in some format or dealing with requests across some protocol like HTTP.

You need:

• Overview
• Quickstart
• API Documentation
• Tutorials and Walkthroughs (for prototypical projects)
• Demos

If you're documenting a Low-Distribution Platform 🐯

This project is usually some internal API at a company, or a microservice, is for learning, or is for a highly specialized use (like a single industrial machine). People will be writing code against this project but the source code is opaque and the format is not widely distributed. Less than 10,000 people will probably ever use this project, but more people will use it than it is reasonable to spend time talking to.

You need:

• Overview
• Quickstart
• API Documentation
• Demos

If you're documenting a High-Distribution Open-Source Platform 🐅

More than 10,000 developers will try to use this platform. Your platform has multiple contributors and is used by multiple high-stakes production environments (like fortune 500 companies) or major open source projects depend on it. Or, if you want to be this.

You need:

• Overview
• Quickstart
• API Documentation
• Tutorials and Walkthroughs
• Demos
• Assessments
• (Maybe) a Course (if open source, a course will likely arise from the community)

If you're documenting a Platform-As-A-Service 🦍

If you are a developer-services product and you want people to use your platform because it is part of your business model. It doesn't matter how many people use it now, _you need all these things._

You need:

• Quickstarts in multiple languages
• Overviews from multiple perspectives- get people in other countries to rewrite your overview.
• Active API Documentation- something with a browser-embedded sandbox
• Tutorials and Walkthroughs
• Demos in multiple languages in multiple versions (preserve your old versions!)
• Assessments
• Certifications
• Multiple Courses