Re: A call for documentation
On Sat, Nov 18, 2000 at 12:10:27AM +0100, Tomas Sanchez wrote:
> 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.
Hello, firend. We have not given up! (I assume you have debdoc in mind).
The problem is that I have school now, and rerely some spare time. There is a
lot of work which would take a lot of time.
> 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_")
Well, we have also sections for distributors and contributors (the guru section
is still a section on how to use the software, but it documents also the
specifications, law stuff and the implementation (though not very thoroughly)).
> 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.
A nice idea. We are actually developing a kind of our own format which would
be able to store documentation consisting of parts in different formats. It
would also have a mechanism to convert beteen formats (filters-convertors).
As a result it would be able to output documentation in a number of different
formats (as many as we, or the user, defines).
> 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.
Hey, if you would like to help us, please, tell us something about you, so
that we can see what tasks you could handle. BTW, the other developer of
debdoc (now contracter to "ddoc") is Erik Winn <devvnull@crosswinds.net>.
> ps. I'm setting the reply-to to debin-user@lists.debian.org since that is one of the lists I'm in.
I am no longer a member of debian-user (too much traffic for my little time),
you could only contact me through debian-devel and debian-security
(and of course my official e-mail mox).
--
Happy to hear from a friend,
Pavel Minev Penev
Reply to: