Hi Theo, Theo de Raadt wrote on Sat, Feb 08, 2020 at 03:33:37PM -0700: > Jason McIntyre <j...@kerhand.co.uk> wrote: >> without getting into a discussion about /etc/examples, in this case i >> personally see neither the point of the example config file (so trivial >> as to be questionable) nor the addition to the man page (if the example >> is worthwhile, add it to mixerctl, not the conf page).
> there is additional pieces of "documentation" that occurs here > > - this is a filename, which if placed one directory above., would > perform a function > - the comment format of the file is demonstrated > - the basic format of the file is demonstrated (is it simply a series > of name=value, or have we created a richer DSL) > > you can argue that is in the manual page. It is. After you read a > lot more. There is a pace-of-learning going on here. Noone ever > demanded that learning must come from a man page, additional sources > of transient information are not prohibited, but I'm picking up a > disdain for information learned any other way... 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. Of course, you have valid points that examples can be particularly fast for picking up information (when they are short and unless you happen to draw incorrect conclusions from them) and that copy-and-paste can matter. So, if there is no clear consensus about which arguments matter how much, we probably best leave /etc/examples/ alone. I doubt having a prolonged fight over this is a smart idea. 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. Yours, Ingo
