Comment by justin66
8 years ago
> The examples should have come first, in the synopsis.
That is just a terrible idea. First, if what you're putting in the synopsis is not "a brief summary or general survey of something" then the section is misnamed or the content does not belong there. Examples don't belong there. Second, and more importantly, plenty of commands can do enough damage that people ought to read up on what they do before receiving an example. You're giving someone a false sense of confidence if you throw an example at them first thing. That's appropriate enough in some contexts, but not in official documentation for software tools.
> The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad.
The problems you go on to list have nothing to do with the structure, and everything to do with the content contained within that structure.
> No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial.
Since "documentation experts" write documentation this way, it's hard to imagine why you'd assert this.
I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant.
That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.