> With one caveat: Norm Walsh recommends DocBook XML as the only path
> with future growth. That leaves us with a hard choice: If we need
> to follow someone, all the other DocBook initiatives are using
> DocBook SGML and will convert 'someday soon', but if we take the lead
> into DocBook XML, we will face a steep learning curve.
>
A good point. I had forgotten that this move was being made. My
personal thought is that if we are going to be developing things new, then
we should use the XML and just eat the learning curve, since we would have
to do it at some point in the future anyway, we might as well all do it at
once rather than each of us attempting a little bit at a time to convert one
part of a set of documents later. It would also save us from having to
convert later, so we can kind of think of it as an investment in the future.
If we choose to go the XML route, since most of the other groups
haven't been using the XML versions, we are going to have to deal with not
having someone else to go look off of, but on the other side, we will be
able to help them by providing them examples of one way in which it could be
done. I haven't gone cruising through the DocBook site yet to know how
difficult it will be to pick up DocBook XML, so if anyone wants to go check
it out at http://www.oasis-open.org/docbook/ and give us some thoughts, that
would be great, otherwise, I will look and comment later on it when I've had
a better chance to look at it.
> C> Thoughts and suggestions?
>
> We should solicit kernel developers to throw random tidbits at us.
> In particular, I expect just about everyone has some aspect of their
> work so dramatically changed from the days of the Beck and Card books
> and the LKHG that they'd want to warn readers of those works.
>
Agreed.
If you want to get really interesting, but slightly complicated. It
would be very cool to have something like the commenting system that
www.php.net has for it's documentation and code. That way if something was
misunderstood or hard to under stand, you could point a developer to it, and
ask them to add some comments, or check and see if it was correct.
(Proactive developers might even add things as they make the changes.) If
you found some way to add watches to the pages, when ever someone made a
comment it could send someone an e-mail so that they can go and see if
something should be added to the page or include a question/answer item into
a FAQ Knowledge Base.
> Perhaps, unless they have it already, kernelnewbies will install a
> FAQ-o-matic (if not, I can put it on my website or on kernel.org) and
> then we just need the kernel authors to send us answers, diagrams, use
> patterns, or anything else they can think of to give new developers
> some context to understanding kernel sources. We could also data-mine
> the kernel archives for question/answer pairs to put into the FAQ and
> hopefully some structure will evolve over time.
>
Having said the above about a FAQ Knowledge Base, I realize that the one
problem is the age of the data if we data mine or any other question/answer
system. At a certain point, data may become obsolete or wrong as things are
changed. I suppose its an implementation detail about how to handle that,
but I thought I would mention it.
Matthew M. Copeland
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Mon Aug 07 2000 - 21:00:06 EST