On Fri, Sep 01, 2006 at 02:10:00PM -0400, Dossy Shiobara wrote: > I know that the sad state of the documentation has been a big problem > for a long time. I'd really like to hear suggestions from everyone as > to how we might go about solving it.
As with code, one of the more effective ways to improve documentation is often to have a clear and demanding customer for it. So, I have to ask, internally at AOL (for Dossy) and/or in other development groups (for everyone else), just how do new developers learn about AOLserver? And does that happen often? > Does it all have to be written by one or two people? Can the work be I suspect that one or two experts must provide at least the editorial voice and oversight. They probably also need to write at least the tricky parts themselves, especially the brand new (and as yet little used) features, and the more interesting non-API docs, like explanations of the internal architecture and design, advice on how and why to do things in particular ways, and the like. > distributed? Where do we start? Should we take the old documentation > and just freshen it up? Yes, of course. The docs could use refreshing, corrections, and additions for the new features. There's no reason to throw out all the older info that's already there, and largely correct. > Do we need to start with a new draft Table of Contents and start > over? Rather, I would say, add any missing sections you think SHOULD be there to the table of contents, as a partial roadmap of what you'd like to accomplish. -- Andrew Piskorski <[EMAIL PROTECTED]> http://www.piskorski.com/ -- AOLserver - http://www.aolserver.com/ To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of your email blank.
