NetBSD-Docs archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

(Re-)Structuring NetBSD user documentation


these thoughts have been in my mind for some time, and finally I formulated

Imho, currently NetBSD's documentation has, despite being great and better
than anybody else's, three major problems:
 * It is too scattered. There is documentation everywhere. Sometimes in the
   source code, sometimes in a manpage, in a wiki article, in the guide, in a
   separate article, on a mailing list post, in the installation notes...
 * It is too diverse to contribute easily. Want to change something written
   on a manpage? Learn mdoc. In the wiki? Write somewhere to post it, as you
   cannot get an account. In the guide? Write terrible docbook, or install a
   docbook writer. On the website? Write docbook or xml with xslt (?!) or html
   or whatever it currently is and install thousands of packages to build it.
 * It does not have a clear target audience. In the guide, on the one hand
   you find a chapter that describes how to install a new system, on the other
   hand, there's a description of the LVM.

Plus, times and audiences have changed. You can assume that
 * A reader will be either somehow familiar with Unix/Linux (that's what you
   can assume in most cases), or interested in a special way. There is no
   need to use NetBSD, people who do it, *want* to use NetBSD.
 * The described audience is more likely not reading text sequentially, but
   search for the information they're looking for, or read in a
   network-structured manner.
   That's what Wikipedia, Wikis and Google did to our minds.
 * Most likely, a web search engine is the starting point for it all. There
   is no need to describe Unix tools, vi, X or PAM - they're standard.

All these problems are already addressed, but everything separately.
I wonder: Isn't there a way to combine all or most of these things?
Just some ideas:
 * create a homepage which links documentation sorted by relevance and
   usefulness and not technical correctness
 * integrate manpage and wiki and website search
 * convert the guide to separate wiki articles which have a special status in
   that they're more throughly looked at, and there is a script which merges
   them all.
 * convert installation notes and separate articles to something else... wiki

That's already the point where I'm still thinking.
Is markdown *the* language we want to use for everything? It is very easy to
learn and write, but it's very restricted in its usage. If you think further
about it, modifying man tools and converting manpages to markdown would be
the consequence of this - but also losing much information as markdown is not
as rich as mdoc is (please correct me if I'm wrong). And making it impossible
to export single projects separately (as was discussed before), though there
are (very restricted) markdown->mdoc converters.

Regards, Julian

Attachment: signature.asc
Description: PGP signature

Home | Main Index | Thread Index | Old Index