Doc Team Suggestions

Documentation Style

Click here for the suggestions on documentation style.

Create a section with your name and write your suggestions on the Table of Contents (TOC). Let's wiki this!

Vítor Souza's Suggestions

Documentation:

One-paragraph description of what is WebWork. And then, an explanation of how the documentation is divided:

...

(details on each of the above follows)

Overview

1. What is WebWork
2. Comparison to Struts (Tapestry, VRaptor, JSF, etc.?) WebWork community
3. Mailing lists / Forum
4. Bug tracker
5. Wiki
How to contribute?– current material and links to existing articles
6. Articles and press about WebWork
7. Projects using WebWork / Testimonials

Project Information

1. License
2. Deployment notes
3. WebWork versions
   • Current release
   • Previous releases
   • Migrating from WebWork 1.x;
4. Dependencies
5. WebWork Team
6. WebWork community
   • Mailing lists / Forum
   • Bug tracker
   • Wiki
   • How to contribute?

FAQ

1. Category 1
2. Category 2
3. Etc.

The questions included in the FAQ should be extracted from the User Forum/Mailing List. Someone could review recent messages and find out which questions are asked the most. After that, separate the questions into categories to form the subsections.

Tutorial

1. Downloading and installing WebWork
2. Setting up the test environment (to test tutorial source code)
3. Basic configuration and your first action (Hello WebWorld)
4. Understanding actions (includes note on displaying data using Scriptlets)
5. Understanding results
6. Meet WebWork tag library (would also explain a little bit of OGNL)
7. Evaluating other view options: Velocity
8. Evaluating other view options: FreeMarker
9. Understanding interceptors
10. Performing validation
11. Performing dependency injection (IoC) through components
12. Going i18n (internationalization)
13. Retrieving data without a full request using XHR/Ajax

This should be in conformance to Patrick's example app. Vitor will talk to Patrick to get his opinions on the sequence of lessons suggested above and how to make the tutorial conformant to the example app.

Cookbook

• Tips and tricks on Application Servers (this was in "Overview")
• Accessing application, session and request objects;
• How to format dates and numbers;
• Other stuff Stuff from the revised current Cookbook...

All the tips in the Cookbook should be revised. Some of them could belong to the tutorial instead (basic stuff). 3rd party integration tips could be separated from the rest. Also, it would be good if all of them also followed the same structure, kind of like a tutorial lesson, but on advanced topics. The differences between the Tutorial and the Cookbook would be:

Reference

I like Jay Bose's reference TOC (below). On top of it, I'd suggest:

Remove "What is WebWork" and "Getting Started/Deployment Notes";

Replace them with "Introduction", in which there would be instructions to read the Overview first and proceed to the tutorial if the reader wants to get started;

Append "/ Dependency Injection" to "IoC", because some people may know it only by the name "Dependency Injection";

Group "JSP & Velocity Tags" with "WebWork Freemarker Support" to create a single section that contains everything related to user interface (in subsections);

"JSP Expression Language Comparison with WebWork 1.x" should be in "Migrating from WebWork 1.x", in the "Project Information" section;

Add to that same UI topic: JavaScript validation and DWR support (is this in 2.2?);

WebFlow would be in "Related Projects";

...

A question that arised in the TOC discussion was: what's the difference between the Cookbook and the FAQ? Well, some of the items in the Cookbook are also FAQs (people ask about them a lot), so they would also be included in the FAQ, with links to the Cookbook. The FAQ should have quick answers or link to longer answers, such as the Cookbook. The Cookbook is tutorial-style, a collection of mini HOW-TOs.

Reference

1. Introduction – This will have parts of Overview in it, rather than forwarding them to Overview altogether.
2. Architecture
3. Configuration
4. Interceptors
5. Action Chaining
6. IOC / Dependency Injection
7. UI Components - JSP, Velocity, Freemarker, JavaScript validation and DWR support
8. Result Types
9. Type Conversion
10. Validation
11. OGNL / Object Graph Navigation Language
12. Internationalization
13. 3rd Party Integration - Sitemesh, Spring, Pico, Hibernate, JUnit, Quartz, etc.

An important thing about the reference is that it should be written in book-style (or hibernate-reference-style) so a PDF version would be generated and people could print it, pass it around the office or read it while working out or relaxing in bed. Therefore, Confluence's PDF features play a big part in this. Some questions that came up during the discussions:

• The reference could link to other pages in some situations. Links in confluence do not reference URLs, but the page's names. Does Confluence convert them to the URL before writing the PDF? If not, should the Reference not link to any pages outside it?

• Can we select which pages are converted into PDF? If we want to convert only the Reference to PDF, can we do that? How does that work?

Related Projects

1. WebFlow (graphical chart tool)
2. EclipseWork (Eclipse Plugin)
3. IDEA Plugin
4. WebWork Optional
5. Etc. ?

Jay Bose's Suggestions

Suggested standalone documents (that may be viewed as single html, multiple html chapters, or PDF):

• Reference manual
• Tutorial

Suggested wiki sections/pages:

• FAQ
• License
• Cookbook
• Webwork Community
• Webwork versions
• Articles about Webwork
• Projects using Webwork
• Comparison to Struts

Suggested Reference TOC:

1. What is Webwork – also explain what Webwork is not.
2. Architecture
3. Getting Started/Deployment Notes
4. Configuration
5. Interceptors
6. Action Chaining
7. IOC
8. JSP & Velocity Tags – this would be the current tag information, combined with the current "JSP Expression Language Comparison with Webwork 1.x" pages
9. Webwork Freemarker Support
10. Result Types
11. Type Conversion
12. Validation
13. OGNL
14. Internationalization
15. Webflow
16. 3rd Party Integration

...