Programmers hate documentation. The reason probably lies deep in the psychology of coders, but it’s easy to imagine why: Coders hate reading instructions (even though they spend their days writing instructions). Coders may buy furniture from IKEA, but never has a coder read the instructions to put it together. Also, once they have written instructions, coders don’t see the point to writing instructions about instructions. Meta!

But times are changing in software, and now–whether you like it or not–it’s time to pay attention to your documentation. If your project is a COSS project, great documentation is table stakes for success.

Documentation is easier than ever to write

The days of banging out technical writing on a keyboard from a blank page were over decades ago. In a sense, documentation has been self-writing for a long time. Even those coding in the last century will remember Oracle’s Java “self-writing” documentation, known as Javadoc. Developers put tagged comments directly into source code (/** … */) and the javadoc tool then automatically parsed these comments to generate HTML documentation.

Self-writing documentation was a big improvement over no documentation, and it was great idea to connect documentation to code, rather than for the two to be separately created. But self-writing documentation relied on developers to document code as they wrote. Unfortunately, coders don’t work that way.

Today, AI can write most documentation–or at least, a first draft for humans to review. Using AI is not a panacea, but it takes a lot of the grind out of the job. As one technical writer mentions, “AI can be a collaborative partner in creating and organizing documentation while remaining technically precise.”

Moreover, your community can use AI to query your documentation. A good way to test your documentation for completeness or quality is to run some sample queries on it. Better yet, you can even train your own fine-tuned AI to help your users.

So, there is no excuse anymore for not writing complete documentation. It’s not a negligible task, but it’s becoming a manageable one.

Documentation signals project quality

One obvious difference between an amateur project and a serious project is documentation quality. When you are trying to maximize adoption of your project–as opposed to merely scratching a development itch for yourself–you need clean, easy-to-understand instructions.

Installation documentation is particularly important, because it is used by everyone. Build instructions are key whenever your project has to be custom built. Technical documentation is important to developers who may need to customize your code or integrate it with other platforms or software elements.

You need to anticipate all the kinds of users for your project, and all the platforms that adopters might need to use. This requires some thought, but it is also a great way to get your community involved with your project. You should try to anticipate user needs, but at the end of the day, the users know best what they need. If you get issues posted for your project, first ask yourself if they could have been avoided with documentation. If so, it’s time to make some documentation improvements.

Documentation helps involve non-coders in your project

One of the challenges we hear consistently about open source collaboration is lack of diversity. Documentation is a great way to ease into addressing that problem; you can involve all different kinds of contributors by seeking collaboration on documentation. By doing this, you avoid the “pipeline problem”– that potential contributors have a uniform and concentrated background.

Making a distinction between documentation and “technical work” is a false dichotomy. There is a spectrum of skills in open source that ranges from coding, to UI design, to technical writing, and beyond, and a good project needs all these skill sets.

Language localization is low hanging fruit: users are often happy to contribute suggestions on how to make software useable in their own language or locale. And it takes no coding experience to make suggestions to documentation. In fact, non-coders can be better at improving documentation than coders. By inviting community members to contribute to documentation, you may even be teaching someone technical writing, and getting them started on the path to open source collaboration.

Documentation boosts SEO (and AEO)

Who’s reading that documentation you write? Users and developers read documentation, but search engines and LLMs ingest it, too. Now, consider what happens if a search engine or LLM recommends using your project for a purpose you have identified in your documentation. That’s the best kind of free marketing, and it will help you drive adoption of your project.

These days, developers are relying more and more on the recommendations of LLMs or search engines backed with AI. So, make sure the use cases for your project are well documented, in a form that is available for spidering or training. Don’t mark it “No AI.” Documentation is not a monetizable product, and so you should make it as freely available as you can.

So, it’s time to recalibrate your thinking about documentation. Find new ways to create documentation, let documentation help you with user support, and let it help you broaden your community. Take it seriously, and it will help you build a serious project.