How to Write Helpful Documentation

The usefulness of project documentation is not only to describe “what this is,” but also “why this is done this way.”

Describe the reasons why the application works the way it does. Talk about the problems you encountered during the development and how you solved those problems.

Ideally, a newcomer reading the docs should learn about all the compromises and controversial decisions in the project. Because without them a huge amount of context is lost, and new developers are likely to repeat old mistakes.