Debbie, +1 for prettying up the wiki. The addition of a navigation bar would really help make it easier to find content and add a sense of structure to it. If you want to work on this it would be great. As for how to do the documentation, I'm still thinking. Dan D. has made a good case for using the wiki, but I still have concerns. Largely, I think those concerns are more philosophical than practical, but I need to chew on it a bit more. Cheers, Eric
> -----Original Message----- > From: Debbie Moynihan [mailto:[EMAIL PROTECTED] > Sent: Friday, September 15, 2006 10:31 AM > To: [email protected] > Subject: Re: Wiki and Web > > I think that both the dynamic wiki based docs and the release level docs > both have significant value. I do think that the expectation of an open > source project is not the same as traditional commercial software so just > wiki based documentation would be acceptable. That said, release level > documentation would be really beneficial for users and a nice to have. I > have a lot of experience with customizing templates for communities and > web-sites and writing copy/documentation (although I am new to Confluence > but it seems pretty easy). I'd like to volunteer to expand the wiki > format > using Confluence themes (left navigation theme) and best practices from > apache projects and other confluence based projects listed previously in > the > thread. Eric would it make sense to hold off and see how the > documentation > progresses for a bit and then determine if we also want to create separate > formal release level documentation - or if you want to get going on the > docbook documentation right away you can focus on that and you won't have > to > learn as much about Confluence. I've done some research on Confluence > themes > etc and it seems pretty straightforward, although I will need wiki admin > privileges (preferred) or I can provide instructions to someone with admin > privileges. My user name is DebbieMoynihan on Confluence. > > Whatever we decide on the documentation, I think it makes sense to use the > left nav bar theme so we can see all of the critical links to the left > instead of having to scroll to the bottom of the page. > > Debbie > > On 9/12/06, Johnson, Eric <[EMAIL PROTECTED]> wrote: > > > > Oisin, > > Your points are well stated as always. I think they hit a lot of the > > contentions spot on. > > As I writer, I find that wikis are limited for the type of work I want > > to do. I want to create formal documentation that supports a stable > > release. This documentation is targeted at users who are developing > > production systems and are not likely to jump to the next hot release. > > This type of documentation is not really benefited by agility, is highly > > organized, has a consistent level of quality, is thoroughly reviewed, > > and follows some pretty tight style guidelines. It has indexes and other > > aids to finding information in it. > > However, for developers who want to get documentation about how their > > code works or how it is designed a wiki is more than enough. Wikis > > provide a quick and easy way of creating content and keeping it updated. > > For cutting edge, fluid material they are great. Experience has shown me > > that having a wiki available to the engineers does encourage the flow of > > information from the developers to the writers. > > I like your idea of a blended approach where developers create content > > about their features, and users can add stuff also, using the wiki. This > > stuff can be easily published and made easily accessible. In addition, > > we can filter that information into formal documentation that is more > > tightly controlled for quality, style, tone, message, etc.. The more > > formal documentation can also be accessed on through the web site and be > > released as a separate package if that makes sense. > > I know this seems like a "corporate" way of thinking, but there must be > > a good reason that there is a whole industry out there for creating > > formal documentation for popular open source projects. > > Cheers, > > Eric > > > > > -----Original Message----- > > > From: Hurley, Oisin > > > Sent: Monday, September 11, 2006 6:57 AM > > > To: [email protected] > > > Subject: Re: Wiki and Web > > > > > > Lots of interesting points here on the documentation aspect of the > > > project, and I'm enjoying the thread :) Of course I can't resist > > > adding my 2c, in bullet point form. > > > > > > * having worked as a developer for a number of years, I have > > > regularly seen releases 'released via press release' and then > > > the documentation follow the code within a 30 day ship window > > > > > > * having used OSS for a number of years, I have regularly seen > > > documentation updated at a very fine-grained level and in a > > > timely fashion when bugfixes happen...also I have seen documentation > > > that never actually appears :) > > > > > > * I disagree that wikis are unprofessional, I think that they > > > are very acceptable - if it's good enough for IBM, BEA, Oracle, > > > SAP and co. (http://www.osoa.org/display/Main/Home) then I think > > > is has made it's professional debut. However, some wikis can > > > look awful *cough*moinmoin*cough* :) > > > > > > * I, personally, find it easier to write for wiki than docbook, > > > purely because I level of tooling required for wiki is less than > > > that required for docbook given a set level of productivity. > > > However, if I was writing full-time or mostly full-time, then I > > > wouldn't use the wiki, I would use docbook. > > > > > > * I, personally, find wikis very frustrating because I can't > > > update them offline without copying and pasting. Some day I > > > will need to fix this. > > > > > > * I, personally, think that using a wiki strengthens the developers > > > connection to the document and increases their resolve to actually > > > update the thing in the first place. Remember that one of the > > > big challenges a tech writer has is actually getting information > > > out of the developers - blood/stone and all that (generalization > > > alert :) > > > > > > * I, personally, think that a developer is not anywhere as likely > > > to be able to write as well as a tech writer, so I think > > > that it is a positive thing for those skilled in the exposition of > > > technical <language-of-choice> to filter/review the documentation. > > > > > > Of course, after making all those points the only conclusion that > > > I can come to is that we might need to end up with a blended approach, > > > so that during the development cycle developers can update a wiki, > > > so that snapshots are up-to-date documented, and then coming up > > > to a release perhaps the documentation developers can engage to > > > move, prune, clean and otherwise sanitize the wiki content and > > > transfer it to a docbook format for a doc release synched with > > > the software release. That way everyone gets to use their own > > > fave tools, the code devs can make fine-grained immediate > > > changes to pieces of wiki and doc devs can have a fairly reliable > > > corpus upon which to base release doc. > > > > > > Thoughts? > > > > > > --oh > > > >
