Personally, I prefer the style which the GNU Coding Standards describe:<p>----<p>Programmers tend to carry over the structure of the program as the
structure for its documentation.  But this structure is not necessarily
good for explaining how to use the program; it may be irrelevant and
confusing for a user.<p>Instead, the right way to structure documentation is according to the
concepts and questions that a user will have in mind when reading it.
This principle applies at every level, from the lowest (ordering
sentences in a paragraph) to the highest (ordering of chapter topics
within the manual).  Sometimes this structure of ideas matches the
structure of the implementation of the software being documented--but
often they are different.  An important part of learning to write good
documentation is to learn to notice when you have unthinkingly
structured the documentation like the implementation, stop yourself,
and look for better alternatives.<p>[…]<p>In general, a GNU manual should serve both as tutorial and reference.
It should be set up for convenient access to each topic through Info,
and for reading straight through (appendixes aside).  A GNU manual
should give a good introduction to a beginner reading through from the
start, and should also provide all the details that hackers want. […]<p>That is not as hard as it first sounds.  Arrange each chapter as a
logical breakdown of its topic, but order the sections, and write their
text, so that reading the chapter straight through makes sense.  Do
likewise when structuring the book into chapters, and when structuring a
section into paragraphs.  The watchword is, <i>at each point, address the
most fundamental and important issue raised by the preceding text.</i><p><a href="https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;standards.html#GNU-Manuals" rel="nofollow">https:&#x2F;&#x2F;www.gnu.org&#x2F;prep&#x2F;standards&#x2F;standards.html#GNU-Manual...</a>