Expert Python Programming - Third Edition

Limit the scope of information

There's a simple sign of bad documentation in software—you cannot find specific information in it, even if you're sure that it is there. After spending some time reading the table of contents, you are starting to search through text files using grep with several word combinations and still cannot find what you are looking for. But you're sure the information is there because you saw it once.

This often happens when writers do not organize their texts well with meaningful titles and headings. They might provide tons of information, but it won't be useful if the reader is not able to scan through all the documentation for a specific topic.

In a good document, paragraphs should be gathered under a meaningful heading ...