Eric Holscher, the author/maintainer of Read the Docs, has a saying, “Docs or it didn’t happen.” This is a stance we tend to take in Webdev. Our libraries come with docs, our sites are documented for install and development (as well as some internal APIs), and even our onboarding is documented.

Our Webdev bootcamp is one of the first thing we show new hires when they are getting setup. It includes style guides, pointers to who you need to ping for what accounts, and tons of other basic knowledge about being part of the team. Having this clearly documented gives us a couple things. First, it helps our new developers to be more self-sufficient, they are still encouraged to ask questions, but they have a document they can read to answer the most common questions. Second, it gives us a place to point out well-written, consistent, peer-reviewed and edited, answers to questions.

It turns out this is the whole point behind documentation, and sometimes that point is missed. The value of consistently answering questions that people have is huge. It can be incredibly frustrating when you are new to something and people give you (seemingly or actually) contradictory answers to the same question. Referring to the documentation is better for all parties in involved.

An example of a project with docs is Zamboni. We have complete installation directions, public API documentation, as well as information on other tasks that may require more than basic knowledge to get done (like setting up payments or how we run in production.) The point of these docs go beyond just onboarding new contributors, it is also for those of us who work on the project! Things like the settings changelog give you a place to look if suddenly things aren’t working. If there is a component or API you don’t work on very often, you can check the docs for how to configure it and basic usage.

This emphasizes the value of internal documentation for projects. These advantages don’t disappear just because your project isn’t open source (though you should try to open source as much as you can), because you’ll always have questions that are frequently asked by your team when they go to work in an area they don’t know very often, or during onboarding.

You’ll notice I mentioned RTD at the start, and then linked to a bunch of documentation we have hosted on there. We use Sphinx for our documentation, it is a very powerful tool written in python (though it is used by other languages) which RTD can automatically build and host for you. The value add is huge and makes it even easier for us to maintain our documentation which is important if you want people to actually be able to access the latest version of your docs.

If you too are part of documentation culture, or perhaps would like to join that culture, there is a relevant conference coming up that Mozilla is sponsoring, Write the Docs. It is for more than just RTD users. The speakers come from a variety of backgrounds, which will hopefully lead to a diverse group of people all together in the name of documentation.