Write documentation that actually works for your community

What distinguishes successful and sustainable projects from those that disappeared into the void? Spoiler — it's community. Community is what drives an open source project, and documentation is one of the foundational blocks for building a community. In other words, documentation isn't only about documentation.

Establishing good documentation can be difficult, though. Users don't read documentation because it's inconvenient, it goes out of date very quickly, there's too much, or there's not enough.

The development team doesn't write documentation because of the "it's obvious for me, so it's obvious to everyone" trap. They don't write because they are too busy making the project exist. Things are developing too fast, or they're not developing fast enough.

But good documentation remains the best communication tool for groups and projects. This is especially true considering that projects tend to get bigger over time.

Documentation can be a single source of truth within a group or a company.  This is important when coordinating people toward a common goal and preserving knowledge as people move on to different projects.

So how do you write appropriate documentation for a project and share it with the right people?

What is successful community documentation?

To succeed in writing documentation in your community:

• Organize your routine

• Make it clear and straightforward

• Be flexible, make changes to the routine according to a specific situation

• Do version control

Image by:

(Olga Merkulova, CC BY-SA 4.0)

Being flexible doesn't mean being chaotic. Many projects have succeeded just because they are well-organized.

James Clear (author of Atomic Habits) wrote, "You do not rise to the level of your goals. You fall to the level of your systems." Be sure to organize the process so that the level is high enough to achieve success.

Design the process

Documentation is a project. Think of writing docs as writing code. In fact, documentation can be a product and a very useful one at that.

This means you can use the same processes as in software development: analysis, capturing requirements, design, implementation, and maintenance. Make documentation one of your processes.

Think about it from different perspectives while designing the process. Not all documentation is the right documentation for everyone.

Most users only need a high-level overview of a project, while API documentation is probably best reserved for developers or advanced users.

Developers need library and function documentation. Users are better served by example use cases, step-by-step guides, and an architectural overview of how a project fits in with the other software they use.

Image by:

(Olga Merkulova, CC BY-SA 4.0)

Ultimately, before creating any process, you must determine what you need:

• Focus groups: this includes developers, integrators, administrators, users, sales, operations, executives

• Level of expertise: Keep in mind the beginner, intermediate, and advanced users

• Level of detail: There's room for a high-level overview as well as technical detail, so consider how you want these to be presented

• Journeys and entry points: How do people find the documentation, how they use it

When you ponder these questions, it helps you structure information you want to communicate through documentation. It defines clear metrics on what has to be in the documentation.

Here's how to approach building a process around documentation.

Coding conventions

The code itself should make sense. Documentation should be expressed through good class names, file names, and so on. Create common coding standards and make a self-documented code process by thinking about:

• Variable naming conventions

• Make names understandable by using class, function naming schemes

• Avoid deep nesting, or don't nest at all

• Do not simply copy-and-paste code

• No long methods should be used

• Avoid using magic numbers (use const instead)

• Use extract methods, variables, and so on

• Use meaningful directory structures, modules, packages, and files

Testing along with engineering

Testing isn't only about how code should behave. It's also about how to use an API, functions, methods, and so on. Well-written tests can reveal base and edge case scenarios. There's even a test-driven development practice that focuses on creating test cases (step by step scenarios of what should be tested and how) before code development.

Version control

Version control, even for your documentation, helps you track the logic of your changes. It can help you answer why a change was made.

Make sure comments during commits explain WHY a change was made, not WHAT change was made.

The more engaging the documentation process is, the more people will get into it. Add creativity and fun to it. You should think about readability of documentation by using:

• software code conventions

• diagrams and graphs (that are also explained in text)

• mind maps

• concept maps

• infographics

• images (highlight important parts)

• short videos

By using different ways of communication, you offer more ways to engage with your documentation. This can help forestall misunderstanding (different languages, different meanings), and different learning styles.

Here are some software tools for creating documentation:

• Javadoc, Doxygen, JsDoc, and so on: Many languages have automated documentation tools to help capture major features in code
• Web hooks and CI/CD engines: Allows continuous publication of your documentation
• Restructured Text, Markdown, Asciidoc: File formats and processing engines help you produce beautiful and usable documentation out of plain text files
• ReadTheDocs:  Is a documentation host that can be attached to a public Git repository
• Draw.io, LibreOffice Draw, Dia: Produce diagrams, graphs, mind-maps, roadmaps, planning, standards, and metrics
• Peek, Asciinema: Use commands for recording your terminal
• VokoscreenNG: Use mouse clicks and screen capture

Documentation is vital

Documenting processes and protocols are just as important as documenting your project itself. Most importantly, make information about your project and creation of your project exciting.

The speed of entering into a project and process, and understanding how everything works, is an important feature. It helps ensure continued engagement. Simple processes and a clear understanding of what needs to be done is obtained by building one "language" in the team.

Documentation is designed to convey value, which means demonstrating something through words and deeds. It doesn't matter whether it's a member of your team or a user of your application.

Think about the process as a continuum and use means of communication, processes, and documentation.

Image by:

(Olga Merkulova, CC BY-SA 4.0)

Documentation is a means of communication.