3 ms·
Personally, I prefer the style which the GNU Coding Standards describe: ---- Programmers tend to carry over the structure of the program as the structure for
by teddyh 11y ago
Personally, I prefer the style which the GNU Coding Standards describe:
----
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.
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.
[…]
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. […]
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, at each point, address the
most fundamental and important issue raised by the preceding text.
https://www.gnu.org/prep/standards/standards.html#GNU-Manuals https://www.gnu.org/prep/standards/standards.html#GNU-Manual...
- awinter-py 11y agognu is in many ways wonderful but documentation is not one of the ways. gnu's two docs challenges are (1) document the command-line flags for users and (2) document the code for contributing devs. I've never faced case 2 but wading through man pages for case 1 is less than awesome. I agree that docs should answer the user's typical questions but gnu docs seldom do. Can you imagine trying to figure out gnu tar from the man page? You never would. Doesn't help that search engines starting with G view queries like 'tail -f' as stopwords.
- bpchaps 11y agoI dunno, I find them much better than most of the documentation I've worked with. I agree with you for beginners, since when I first started reading man pages and such, I wanted to rip my eyes out. But after a while, once I learned why the documentation was written the way it was, the flow of it started to make more and more sense. Though, in a lot of ways this comes from personal opinions that gnu tools and by extension, gnu/linux, should be difficult in the worse-is-better sense. These days, when looking at documentation, my go-to example for awful documentation is salt. Because, well, this is utter bullshit: $ man salt 2>/dev/null | wc -l 133324
- catnaroek 11y agoI find GNU info more useful than man pages as documentation for those who are learning how to use a program. The documentation is structured and hyperlinked in a very convenient way. On the other hand, the terseness of man pages is more convenient for those who already mostly know the program, but need a reminder of minor details like the exact command line flag to enable a specific program option.
- bpchaps 11y agoAgreed, but unfortunately info is used so infrequently that I don't even bother with it these days.
- jandrese 11y ago95% of the time when I'm opening a manpage I am looking for a particular command line option or syntax. With man pages I just hit / and then a relevant keyword and it jumps to the right section. With info pages I have to grok which section it might be in, then remember what arcane ctrl sequence follows links and then what sequence searches in the document then which sequence goes back because I guessed wrong. I find manpages to be much more convienent, even though they are less structured.