I am sorry for not being as active as I would like. I asked our graphics designer to design a new logo for Turbine. As soon as we have something I will submit it for approval. May be later we could do a face lift to the whole site.
I think is more important to have a quality and coherent documentation than to have tons of documentation. May be many specific questions could be resolved with a FAQ. -- Humberto > -----Original Message----- > From: Quinton McCombs [mailto:[EMAIL PROTECTED] > Sent: Friday, March 14, 2003 5:27 PM > To: Turbine Developers List > Subject: RE: Proposal: Documentation Campaign > > > > -----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] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
