+1 I think this is an excellent idea. I know I try and toss into the wiki various things as I discover them. Having a single manual would help things a lot. Also, having a standard format to work in would be great.
I think having a documentation lead who settles disputes is the way to go, otherwise things break down into endless disussions about how to document, versus actually getting documentation done! I am definitly willing to help document things. Eric -----Original Message----- From: Chris K Chew [mailto:[EMAIL PROTECTED] Sent: Friday, March 14, 2003 4:56 PM To: [EMAIL PROTECTED] Subject: Proposal: Documentation Campaign Hello! There has been quite a bit of talk about Turbine documentation recently, and there are a number of people eager to participate in the documentation of Turbine. The core problem is that there is no clear mechanism for Documentation in Turbine. Maven helps some, as does the wiki and scarab, but no official single, accessible process has been defined. In my opinion, this is because nobody is responsible for documentation. The overall effect is that brief periods of motivation (such as the Wiki) become lost in the archives of turbine-user or turbine-dev. I propose we begin a campaign to fix this. Below I describe what pieces of documentation I feel we must have, and identify some changes that need to be made in order to commence the campaign. Please take a moment to peruse them, and offer suggestions where you see fit. Documentation We Must Have: 1. Documentation positioning Turbine for potential new users. The time has come when Open Source projects must compete for users. Turbine is an excellent, robust and stable framework; our first impression should be consistent in quality with the rest of our project. 2. A single Complete Reference Manual that is searchable. MySQL offers an excellent example where an old project has maintained consistent, thorough and recent documentation across hundreds of releases. They use a single manual that describes everything from installation to usage, to migration. Having a single reference manual with clear update processes will ensure that the documentation keeps pace with development. 3. Sample App / Tutorial. Often, a big reference manual can be an overload of information to new users. A sample application coupled with a tutorial describing how to develop, build and deploy the sample application will be very helpful in introducing new users to Turbine concepts. 4. Maven Generated Info. Maven is succeeding in its goal to organize software development projects. The maven-generated project information is a very nice feature, and should remain on the website. These include javadocs, xref, release-specific documentation (see below), changes, xref, issue tracking, etc. In Order To Develop A Documentation Process, I Propose: 1. We elect somebody responsible for Turbine documentation. This does not mean they are the only ones who write it, but instead take charge in applying patches, identifying areas needing improvement, updating the website, and soliciting authors. This person must have commit permissions for all the turbine modules, as well as deployment permissions for the Turbine website. 2. All general Turbine documentation belongs in the jakarta-turbine-site module, built by maven along with sub-sites for the various releases. 3. Release-specific information will be separated into two areas: info pertinent to release developers, and info pertinent to release users. The former will remain in the respective release module, the latter will be continuously integrated into the Reference Manual through the application of submitted patches. The developer release information will continue to be accessible from the turbine web site inside the release "sub-site". 4. Developers become responsible for updating documentation when something changes that either developers or users need to know about in order to continue developing or using Turbine. 5. Developers become responsible for writing migration notes *during development*, so that migration is a painless effort with each release. 6. Any new turbine-user threads were a problem is identified and solved must be migrated into the reference manual. Again, I am eager for your suggestions. My main concern is that our current motivation to document Turbine is not lost. Thanks, Chris --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
