Messages in this thread | | | From | "Copeland, Matthew" <> | Subject | RE: linux kernel docs | Date | Tue, 1 Aug 2000 10:00:31 -0700 |
| |
> 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/
| |