> -----Original Message----- > From: Chris K Chew [mailto:[EMAIL PROTECTED] > Sent: Friday, March 14, 2003 3: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.
Very true. > 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. We could also use the help of a good web designer to give the Turbine site a flashier look and feel. Take a look at the cocoon site (http://xml.apache.org/cocoon/index.html). The look and feel of the site really says nothing about the quality of a product but it does give a good first impression. Although jakarta has a common look and feel, we are not bound to it. We are not stuck with what Maven can provide in the way of site generation either. I have some changes that I will be implementing soon on the current site. Basically, I am going to try to make it less confusing to find the right docs. For example, the how-to for extending turbine user for 2.2 is under the 2.2.1 link and not 2.2.0. The link under 2.2.0 is for 2.1. My original intent on publishing the 2.2.0 docs access to the docs for the released version. I did not like the fact that we kept of the 2.2.1-dev and 2.3-dev docs on the site. However, I think I made things worse by doing this. I am going to change this by only having links to 2.2 and 2.3-dev. Under the 2.2 link, you will see the docs for 2.2.1-dev but the API docs for 2.2.0. I am not exactly sure how I am going to do this yet though... > 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. Having the reference manual will not ensure that it will keep pace with development. Turbine has very few active committers. Those people have mainly focused on the code base and documentation has taken a back seat to this effort. This is a fairly common thing to see with developers. What will ensure that it keeps up with the pace is to have a few committers and/or contributors who are interested in maintaining the documentation. We need a few good technical writers who are willing to donate their time. > 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. I think that we need multiple sample applications. I think that two basic applications are needed. One would use Velocity and the other would use JSP. The applications are identical exception for the view technology. These would be used to show the basics of Turbine such as actions, screens, layouts, and navigations. Perhaps an additional same app could also be developed which is much more complex. It would literally use every service that Turbine has to offer. I think this would go much further than our sample code included in the docs right now. > 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. Yes, but only for the released versions and the current development version. Most of the maven reports make no sense for the jakarta-turbine-site. Also, the change log reports only report against cvs head no matter what version you are publishing. > 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. Does someone really need to be elected? I say just let people volunteer. Commit access will generally be given to anyone who contributes a significant amount of effort to the project. This is normally in the form of patches. This will really work itself out because the people who put effort into getting the documentation into shape will end up with commit access. The people who submit the occational patch to the docs will have it applied by the people who do most of the doc work... Until such time as we have someone with commit access who is really focused on the documentation I will take responsibility for appling the patches and publishing the site. > 2. All general Turbine documentation belongs in the > jakarta-turbine-site module, built by maven along with > sub-sites for the various releases. Agreed. > 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". Agreed. > 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. There we go trusting the developers to document as they go... ;-) > 5. Developers become responsible for writing migration notes > *during development*, so that migration is a painless effort > with each release. This seems like a very reasonable requirement. > 6. Any new turbine-user threads were a problem is identified > and solved must be migrated into the reference manual. For common problems, this is not a bad idea. We need to get issues opened in Scarab for every problem that is reported. Scarab is a good tool for tracking issues with the software. We should be using it. We also need to get Scarab better configured for tracking our issues. This is something that I have been meaning to do for some time but have not found the time to do it. For instance when someone creates a defect entry, there is no place to record the version of turbine they are using. When it is fixed, there is no place to record the version that it is fixed in. Why do we have five issue types??? Our installation of Scarab is pretty much a default installation that was not really customized. I think that we need to start a separate thread on this to get it taken care of. I suppose that I need to quite talking about it and write up a proposal. > > Again, I am eager for your suggestions. My main concern is > that our current motivation to document Turbine is not lost. I think that the ideas you have presented here are very good. I nominate you to help up the project.. :-) > Thanks, > > Chris > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
