> Even moderately large systems can be beautifully documented in a > single manual page - for example, a shell
It's amazing how true this is. Even with massive man-pages, it's still easier to find what I'm looking for in less(1) by hitting the `/` key and typing a search string. It's quite literally faster than the time it takes to load web-based documentation (especially on my crappy connection...) I can't think of a documentation format more pure than a well-written man-page. Conversely, the worst-looking man-pages I've ever seen are those which were generated from markdown. Their source-code is actually more readable than the formatted output... :-( On Sat, 1 Dec 2018 at 15:52, Ingo Schwarze <schwa...@usta.de> wrote: > Hi Peter, > > if you are interested in my perspective - scrap the HTML documentation > and fix the manpage. The reference manual - i.e. the manpage - is > really important: when you use some software regularly, you use the > reference manual all your life. Catering to the experienced user > is most important because whoever is serious about using the software > will become experienced sooner rather than later. So the reference > manual (manpage) must be concise, precise, and correct. > > If an author has too much time on his hands and doesn't doesn't know > what to do with it, there is nothing wrong with writing a beginner's > tutorial, too. But it's really not so important. You skim through > that once, than quickly move on to the real thing for further learning, > often even before finishing the tutorial. And then there is never a > need to come back to it, so it doesn't really matter that much - "use > once" is much less important than "use always". > > Besides, even beginners can easily learn from a well-written reference > manual. > > Hell, *especially* when i know nothing about a software and just > need to use it quickly for one task, i invariable go straight for > the reference manual because the relevant bits are almost always > less text to read in the ref docs than whatever "user manual" or > "tutorial" there may be, so reading them takes less time there. > > Write the real manual in some other format than a manpage? Bad > idea. it means you make it harder to access, out of the usual place > where people look for documentation, in a gratuitiously different > format. You want HTML and PDF versions? Not a problem at all with > manpages, after all, typesetting is what Jerry Saltzer originally > designed RUNOFF for. You want hyperlinking? Not a problem with > .Xr links in modern manual pages either. You want bells, whistles, > and moving gifs of cute cats? Bad idea, documentation is about > efficiently conveying information, not about fluff and pictures > and gimmicks. > > You want to exercise the language itself in documenting it? Bad > idea, the documentation is about concisely and simply explaining the > syntax and semantics, and that doesn't require writing the > explanation in the language itself. C library manuals are not > written in C - but they can contain concise examples of C code > in the EXAMPLES section, near the end. Same for mom. > > Even moderately large systems can be beautifully documented in a > single manual page - for example, a shell. If is system is too > large and a single page would become unwieldy, yes, in the first > step, you split it up to the next logical level - i guess for mom > that would be macros, but you can probably judge better than i can > what that next level is. That gives you too many pages, most of > them unreasonably short? So you form logical groups of related > macros, make one page for each group, and name the page after the > most important or typical macro of the group. That page can also > - concisely! - explain the basic concepts relating to that group. > Practically all library manuals (section 3) work exactly that way. > > This is not rocket science and nothing new - just do it... ;-) > > Yours, > Ingo > >