Hi, these thoughts have been in my mind for some time, and finally I formulated them. 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 articles? 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