A call for documentation
Hi debians!
This mail is crossposted to debian-user, debian-user-swedish, debian-devel and debian-doc.
I've done this because I don't really know where to post it since I call for two types of reactions. One is, _yes I want this to happen and I can help, the other being _yes it can be done and this might some way to do it.
My idea is to write a new sort of documentation. (I did read something about something like this some year(s) ago, but I can't find it in the archives, and I think that the developer "just" wanted to learn xml and later dismissed the whole idea.
And now to my point...
The idea is to write task-oriented documentation, yes it's like the HOWTO's, butit shall be oriented towards debian and (this is the most important) be written simultanious in three levels. Theese being:
- Just do it! (what I would like to call the "blackbox")
- How do _you do it? (the "showcase")
- How do _I do it? (the "wuru", like in "_w_anna be _guru_")
The information should be both accesible thru a textfile, so that it's allways there even if you mess up your setup (and if you do, you can't use the "blackbox" level, since you'll have to edit the required files your self) But if the system is somewhat functioning the "blackbox" level could be something like pppconfig, the "showcase" could be like pppconfig except that it reports what it does and why, the "wuru" level could be like the HOWTO's but directed to debian.
Now you might wonder, why I don't just implement such a system. And the answer is this. First, I don't know how to do this. Second, I don't know if it can be done. Third, it might require some standardisation, at least for the "blackbox" level. And this might be a question of strong opinions, which I would like to hear. Fourth, I'm not a maintainer, and maybe that doesn't matter, I don't now.
OK, I think I rememberd to mention everything I wanted to, but if I forgot I'm sure you will remind me...
regards, anarchy&love
tomas
ps. I'm setting the reply-to to debin-user@lists.debian.org since that is one of the lists I'm in.
ps2. This is the second e-mail that I crosspost, and frankly I don't know if this is the correct behaviour so please no flames, just a nice note will stop me from doing this again.
Reply to: