Ingo Schwarze <[email protected]> wrote: > Indeed. When i talk about quality of documentation - which i did > at multiple conferences, last time 2018 in Bucuresti - one of the > first sentences i almost always say is: > > Documentation must be correct, complete, concise, all in one > place, marked up for display and search, easy to read, and easy > to write. > > e.g. https://www.openbsd.org/papers/eurobsdcon2018-mandoc.pdf > first page after the title, second bullet point > > The "all in one place" part has two purposes: convenience for the > user to not have to search multiple places to find it and convenience > for the developer to not have to maintain duplicate information.
It doesn't say and to get us there other sources of information must excluded and exterminated > As long as the manuals are complete and somebody voluntarily > maintains the examples, which seems the case for now, there is > not much harm from the duplication during the time we lack full > consensus. A good example is the httpd.conf example. In your world, someone must read and completely understand a 500-line manual page, and make several difficult inferences and tests, to get close to the resulting example which is a http/https front-end capable of bouncing ACME refresh requests. Noone will arrive there by reading the man page once. Noone will get there in less than an hour. Non-native english readers won't succeed will take even longer. So they'll go use other software. Such strict approaches easily turn into a strong turnoff. A strict policy improving man page quality is one thing, but a policy removing useful short is crazy, and connecting this to manual page quality dissapoints me. t is almost as if the hate for HOWTO has derailed into "you must read our beautiful prose" -- all other approaches indicate user weakness.
