Being open to criticism allows you to write better content.

A first draft is always bad, but writing it begins the process of transitioning from bad -> ok -> good -> great -> inspiring -> transcendent.

Teach first what will help users solve the greatest pains or greatest number of problems, with the relatively least effort to learn.

Demonstrate why to do something rather than stating that it is simply the way something must be done.

Tips take users out of the flow of reading the document, or are missed altogether. It's greatly preferred to integrate the tips into the flow of the content.

Be clear about knowledge assumptions, and provide links to resources for the knowledge you're expecting users to have up front.

When a heading describes a problem, it provides context that allows users dealing with that problem to locate the material related to it.

The Cookbook assumes some user familiarity with the project and provides highly structured documents that walk users through common implementations using the project.

The documentation should provide a comparison with other projects in order to help users understand additional problems the project might solve or create for them, and provide a guide for migrating their project.

It's important to provide a list of changes and how to migrate projects to the new version.

Since the API Reference is not meant to be read top-to-bottom, this is the place to provide in-depth details of the API.

The API Reference provides a complete list of features including type information, detailed use case descriptions, and links to guides, cookbook recipes, and other internal resources that provide more detail.

The Advanced part of the guide targets the next 15% of use cases while also targeting non-essential features, more complex convenience features, and DX improvements.

Linking to other pages or the API reference could be useful, but are best avoided to help users avoid link-hopping and the cognitive exhaustion that can cause.

The Essentials part of the guide targets the 80/20 rule: 20% of the knowledge that will help users handle 80% of use cases.

Guides are intended to make users feel smart, powerful, and curious, and to maintain that state throughout so that users maintain the motivation and cognitive capacity needed to continue learning.

The best APIs are driven by documentation, where feature development is focused on things that are easy to explain.

If you aren't sure about something and have a question, imagine where that will leave users if you don't ask it and provide incorrect documentation.

Users need to understand the context of a problem before they can understand if the solution is relevant to them.

Good documentation teaches users based on their current skill level rather than making assumptions about what they know. Explain jargon and help prevent misunderstandings.

As someone knowledgeable enough to write documentation, it's easy to forget what a new user needs to learn first in order to understand a concept.

Cognitive capacity can be depleted slower by writing simple sentences, presenting one concept at a time, and using concrete, directly related examples.

Without adequate documentation, users can't take advantage of a feature, regardless of its importance or usefulness.

Community has to start with WHY in order to give potential users a reason to join the community and participate.

• WHAT the organization does (products sold/services offered)
• HOW the organization does it (what makes them special/sets them apart from others)
• WHY is the reason the organization exists

In order to attract, retain, and grow, you have to answer the question of why by communicating your vision for a better world served by the community you seek to build.

Activate members by following the "10 at a time rule" and relying on personal relationships to start. Consider seeding conversations using a flywheel.

It's important to choose the platform that's right for your community. Consider key features required to support your vision and features that your audience expects based on their experiences.

A good community has a content cadence with a showstopper, where the cadence is a "minimum required cadence" with a reliable, anticipated prompt. Content types could include events series, product ideation, curated networking, a user blog, AMAs, and a game-ified swag program. The showstopper is something you know your audience will love, and gives them a reason to open the community.

Community concept should be validated through phone interviews with potential members of varying levels of engagement and interests. Validate the goals by asking questions like "What programs are you interested in?", "What communities do you already partake in and why?", and "What can we do to be your go-to space?".

Setting goals for a community is different than setting goals for a product. Community goals should focus on the impact for both members and the company, tie into existing business goals that are already tracked, include "anti-goals" that show what the community will not be used for like "product support", and avoid "stopgap goals".

Some use cases for a community include a place of shared practice centered around skill-building, a place for top-tier access for businesses that center around a creator or consultant providing exclusive access to that creator/consultant, or a real-time workspace that goes hand-in-hand with synchronous experiences like podcasts or working through online courses.

Three ways to understand if you're in the right spot for a new community are having an audience who loves your work, wanting to create a centralized experience for your content, and having the time to launch and manage a new community (which takes a lot of dedication, just like launching a new product).

The main benefits to starting a community are relationships, retention and success, an experimental content pipeline, and an audience that probably already wants a community.

Milestones should have issues attached to them representing the tasks required to complete the milestone. It's important that issues explain why a task is being completed in order to strengthen the vision for the project and help contributors become more involved. It also helps to include extra context like links, relevant people, a description of the problem/idea/feature and potential solutions, and next steps.

Milestones can also be based on short, medium, and long term goals. This is better for projects that have a general idea of time-based prioritization but can't give specific dates. Short term for things being worked on now, medium term for things that contributors can work on now but is not currently being worked on, and long term describes where the project would like to go in the future.

Events are related to sprints or demoing functionality of the project at an event, where you need to know what needs to be complete before and during the event.

A milestone based on a specific deadline.

A milestone dedicated to a project status goal, like building an MVP or completing a specific feature.

The roadmap should include milestones. Milestones can vary from development goals to events.

The roadmap should make it clear how new contributors can jump in to the project.

A roadmap should contain a project mission and summary that orients and welcomes new users and provides a clear picture of where the project is heading.

A roadmap is an opportunity to express the project's vision, which allows users and contributors to understand where the project is heading and to create excitement around the future of the project.

It's important for an open source project to record what the community decides to work on in order to organize the tasks that need to be completed to reach a milestone and to help potential contributors understand the current status of the project and where it's headed.

Explanations are a chance to explore alternative ways to navigate a given situation or to examine opinion-based recommendations.

Explanations provide context for a topic, giving a wider view of the topic or providing the "why" of the topic like design decisions, historical reasons, etc.

Explanations deepen our understand of a topic, even if the explanation isn't something that can be practically applied. It provides context about the topic.

Explanations are a way for the documentation to briefly take a more relaxed stance in order to provide a higher-level view of the topic.

Explanations are rarely created explicitly on their own, but are frequently scattered amongst the other types of documentation.

Explanations expand on a specific topic in order to clarify and illuminate.

Reference guides should always be kept up-to-date with any changes to the codebase.

Describe only. Don't explain, discuss, instruct, speculate, or provide opinion.

Use a consistent, neutral voice for all reference documentation.

Giving the reference documentation the same structure as the codebase allows the user to navigate the code and documentation at the same time, and also allows maintainers see where there are gaps in the documentation.

When looking at an encyclopedia article about an ingredient, you expect to find basic facts about the ingredient as well as potential problems related to the ingredient (like allergy issues). You don't expect to find explanations of what an ingredient is, or how to cook a specific recipe using the ingredient.

Reference guides serve specifically as the "what" of documentation. They don't explain concepts or how to achieve outcomes, they simply tell what the machinery is.

The how-to guide doesn't need to provide steps for every single bit of concept, they only need to show the steps required to achieve the outcome. It's okay if the guide doesn't start at literally the beginning or end at a literally finished product.

A how-to guide should be flexible enough to allow the user to try slightly different ways of doing things and still end up with the same result.

Assume the user already has enough knowledge to follow the how-to. Focus on the end goal, not the context around the goal.

Anything beyond the focus of achieving the stated goal is a distraction and should be omitted.

Imagine a how-to guide as a recipe. The user already understands at least the basics of cooking, otherwise they wouldn't be seeking out a recipe for how to cook something. The recipe is focused solely on the steps required to cook the meal, not how to cook the meal.

A how-to guide assumes some knowledge and understanding on the part of the user.

A how-to guide answers a question that only a user with experience could formulate.

The tutorial should contain only the exact content needed to complete the tutorial. Nothing more.

Avoid abstraction at all costs. The user is new, and abstraction makes it difficult for them to learn. Focus on concreteness.

The tutorial should work for users of all supported operating systems, browsers, frameworks, etc.

If the tutorial doesn't work, the user doesn't learn anything. It's important to build the example in the tutorial while writing it to validate that it works, and to keep the tutorial up-to-date.

The point of the tutorial is to get the user started, not to teach the user all of the project's best practices or ways that experts might do things. It's to give them something to work with, immediately.

The best way for the user to begin is to learn by doing. Tutorials should be focused on enabling the user to achieve an outcome.

Tutorials are what turn people without understanding into new users.

Understanding that each type of documentation has only one job and the difference between types enables an author to know how to write, what to write, and where to write it.

Explanations are understanding-oriented discourses that explain.

References are information-oriented descriptions that describe the machinery.

How-to guides are a goal-oriented series of steps taht show how to solve a specific problem.

Tutorials are learning-oriented lessons that allow the newcomer to get started.

The four types of documentation are tutorials, how-to guides, technical references, and explanations.

This is such a key point to consider. If you've spent all of your precious initial energy on implementing the project, writing a README/documentation after that will just be a headache that you may not even have the motivation to complete effectively.

The README is abstract enough that it provides a direction for the code without being so specific that it has to be changed every time you decide to do something slightly different in the implementation.

The README is the middle ground between having no documentation and having so much documentation that it doesn't allow for exploration. It's a short, single-file source of documentation, meaning that it's long enough to provide a direction for the code that you'll be writing, but short enough that it doesn't get in the way of your creative process.

Writing a README first is essential to establishing a purpose and direction for the code you'll be writing.

It's less about selling your project and more about providing the information needed by a user to effectively determine if your project is what they need. Which is in itself a form of selling, albeit far less direct.

The ordering of elements within a README should be determined by how quickly they allow a user to understand what your project is and if it's relevant to them. You want the user to understand as quickly as possible if your project is right for them—and if it is, why it's right for them.

Common patterns across many modules has created a system of "cognitive funneling" in users' minds. Users expect certain information from a README, and in a specific order.

Users reads in the following order:

1. Name
2. One-liner description
3. Usage
4. API
5. Installation
6. License (does the user actually read this?)

A module isn't a module until the documentation is complete. The documentation isn't complete until a user can use your project without ever having to read the source code to understand something.

Quality > Quantity

It's better to have a short README that nails answering the essential questions but contains no other information/flair than a long, detailed README that answers TOO MANY questions.

A README must make a good first impression on users by answering the following questions:

• What is it?
• What does it look like in action?
• How do I use this?
• What are other relevant details (context) that I need to know about this?

The purpose of documentation is to keep both the author and consumers out of the source code. Answering a question one has by reading the source is significantly more difficult that reading the answer already provided by the README (given that the README is sufficient).

A README allows both the creator and consumers of a project to understand the code contained and its purpose, regardless of the status of development, familiarity with the code, etc. Without a README, a project is simply an artifact lost in time.

Once a project becomes widespread and "too big to fail", it's important to mature the project by establishing a foundation or spec that allows an extreme level of stability in the project and its future, while also possibly establishing a corporate/professional docs team to ensure the highest level of documentation quality.

Once the community is made up primarily of production users, it's now widespread and the basis for a large number of system. It's important to provide documentation filled with examples that make it easy for a user to accomplish any task they may set out to do.

The project has become quite mature with many expert users that need a stable API. Documentation should provide migration instructions, insights into how the project works to solve the problems it targets, and explanations for how to customize for individual use cases. It should also be clear in how these expert users can contribute to the project itself.

One of the most essential pieces of documentation that a mature project should offer is a reader-friendly Changelog. A user should be able to view one source to understand all of the changes that have happened in each version of the project, so they can use new functionality, apply any changes to their own codebase, or understand why certain parts of the system have broken.

Allow the user to understand the future of the project. What's coming down the pipeline?

Complex projects require a lot of context to understand. It's important to write docs that provides a conceptual understanding of the project and its related topics.

The MetaLanguage is the contextual "foundation" of the project. This is everything that isn't directly relevant to the code, like origin story, conceptual understanding, funding/management, future planning, contribution guides, etc.

A tutorial is important for a project as it allows users to dive in, learn by doing, and see results immediately. The tutorial should explain acronyms/jargon, step through APIs, and focus on concrete steps (not abstract concepts).

Any open source project around long enough will start to acquire common mistakes and known issues. It's important to gather these in one place (FAQ?) so that users can easily find these issues and know how to solve them, and to provide links to the project community so they can seek further help if necessary.

Important to help beginners answer questions that might not formulate on their own by providing a series of results-focused steps to solve specific problems. It's important that they are copy-and-paste-able, don't explain concepts (serving more as examples than explanations), and leave out anything that isn't directly relevant to the recipe.

The homepage/README should set a good first impression with users and answer their basic questions like "What is this?", "What can it do for me?", and "Where do I go to learn more?"

In an open source project, "helping contributors" is an important goal of documentation. Maintainers should understand their responsibilities to the project, contributors should understand how to get involved in the project and how it works under the hood, and contributors should be recognized for their contributions to the project.

This is where the project starts to gain the majority of its users. They want use of use + quick wins from documentation that is reliable. Docs should include:

• Status badges
• A tutorial
• Third party plugins/libraries
• How-To Guide/Cookbook/Recipes
• User/Maintainer Content like a blog, meeting notes, talks, third-party blogs, video tutorials, and podcasts
• Comprehensive examples

These are still early adopters as they're okay with some bugs. Docs should include a comparison to other libraries, a problem statement (what you solve, how dev/user is better of with your thing, aka Why You Exist), basic examples, and some live demos.

For very early adopters. It's okay if docs are missing as these users can contribute docs and code. A description with context, a list of features/project goals, and install+config instructions are all that's necessary at this point.

Projects that have just started don't need in-depth documentation. Just a basic one sentence description with an API README.

Write documentation content for specific user personas. It helps make sure the content is relevant and focused.

Length != Quality. It's possible to write too much, at which point you're overwhelming users with more content than is useful to help them solve their problems.

• Homepage/README
• Answer questions where the user expects them
• Project Status
• Install + config instructions
• Config/API Docs
• API Examples
• How-to Guide/Cookbook/Recipes
• Recovering from failure
• Tutorial
• Live Demos
• Third party plugins/libraries
• User/Maintainer Content
• Meta
• Search
• Anti-docs (when NOT to use us; things we will never do)
• Build Docs into the tool

The worst mistake to make with documentation is to assume that people either know everything or know nothing, as if there is no in between.

Part of maturing a project is maturing the documentation. They go hand-in-hand. It's difficult to reach the level of being a mature project without having detailed documentation for users.

Don't be afraid to pivot to different forms of value delivery. If text documentation isn't working or still leaves much to be desired on the part of users, consider shifting to videos or interactive tutorials.

Generate interest with community members by creating content and making sure they're aware of the content.

Charge sooner rather than later.

It's important to play an active role as a community moderator to make sure that the content is high-quality, focused, and relevant.

Prioritize product roadmap with feedback from paying customers.