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
No comments:
Post a Comment