Hi, Anon Loli wrote on Mon, Sep 16, 2024 at 06:39:20PM +0000:
> I appreciate you being nice unlike the offended snowflakes. > My approach to manual pages for my OS will be the following, > which I consider to be THE BEST way for it: No need to yell at me, really. :-) > 1. The manual page should be tested by an audience which you are > targetting which can be newcomers, advanced users or even experts... [...] > explain as much possible without it being too big of a clutter Pretty much what we are doing all the time and what the OpenBSD project has been doing for almost thirty years. The general public uses the documentation, hence testing it, and defects are often reported on our lists. Completeness and conciseness are definitely among our top five goals. > 2. Perhaps use a Wikipedia-like manual formatting, where there are > integrated links into the manual itself or even source code (TempleOS > did this), Hell no. You know, in one of my jobs as a professional programmers, my duties alongside writing and maintaining code, included maintaining documentation in Mediawiki format that the firm made available to our staff (development and support) and in some cases to customers who bought our software. Those parts of that documentation that i wrote were generally lauded by all departments using them, novice users, busy support staff, and specialized programmers alike. In a number of cases, i received email about that documentation ten years after i quit that job. So yes, what you propose is possible and can even be of acceptable quality. But it is much harder to maintain than mdoc(7) documentation and the markup is of vastly inferior quality, both visually and structurally and even more so when it comes to searching, in particular semantic searching. Any Wiki format is objectively an inferior markup format for documentation. > so that you are telling the reader "there's more information if you > are clueless about this subject", but also "this is just a link, so > not to overwhelm you, the reader, and cause you to just search for > some keywords within the manual. Absolutely what we are already doing in our manuals: https://man.openbsd.org/mdoc.7#Xr https://man.openbsd.org/mdoc.7#Sx https://man.openbsd.org/mdoc.7#SEE_ALSO > THIS IS THE BIGGEST UNIX FLAW, AND I STAND FIRM ON THIS! With all due respect, but you might wish to reconsider whether you really know what you are yelling about? The above all-caps claim is baseless even with respect to AT&T UNIX Version 6 (1975), and more so with respect to 4.4BSD (1993), thanks to giants of technical writing and documentation markup like Douglas McIlroy (who is still alive and active on the groff mailing list, by the way) and Cynthia Livingston (who was also alive and well last time i inquired, even though no longer involved in BSD documentation). Also, please do not assume you are entitled to answers from specific people. Regarding making docs newbie-friendly, we absolutely strive for that, too. Just two examples: * man(1) intentionally focusses on basic functionality, avoiding discussion of advanced and more rarely needed features, instead pointing advanced users to the much longer and exhaustive mandoc(1) manual. * sh(1) - designed by Jason McIntyre - focusses on just the basic POSIX functionality, even though our default shell contains lots of more complicated functionality, fully documented in the significantly longer ksh(1) manual. I'm sure you can find more examples of explicitly making stuff newbie-friendly. It's maybe not among the top five objectives, but still a pervasive goal, maybe something like #6 or #7. [...] > So I won't really waste my time on inferior manual technology that > is of UNIX and it's derivatives Linux and *BSD... You might perhaps wish to waste some time to learn why UNIX manual page technology was never inferior in the first place, and why OpenBSD manual page technology is the cutting edge of UNIX documenation technology, which is by the way widely acknowledged. Feel free to start with my half-day conference tutorial: https://www.openbsd.org/papers/eurobsdcon2014-mandoc-paper.pdf https://www.openbsd.org/papers/eurobsdcon2014-mandoc-slides.pdf https://www.youtube.com/watch?v=csA7-SUtUcw Yes, that's 10 years old, and there has been more progress since, but it's still a good place to start and learn the basics. [...] > Like I said - I'd change the entire fucking manual architecture > if I were one of bigger OpenBSD developers, but I am not, so best > I can do is do this for my OS when it is time to create the manual > for people. In general, it's not a good idea to criticize the grand plan of a project when you don't understand how that plan works in the first place, or to start something completely different without understanding requirements, the state of the art, and past experiences. Start with specifics, with small patches, rather than with grand plans, lest you risk producing just cheap talk but no progress. We have a saying round here "shut up and hack", which i violated by writing this message, but maybe it's useful anyway to some newer readers of this list... Want to be newbie-friendly, you know, and occasionally repeat some of the basics as a friendly reminder... Yours, Ingo