GlassFish v3 Documentation Planning Minutes - 12/17/08 Main meetings page Attendees Dixie, Hanan, Gail, Paul, Alan, SueAnn, June, Eric, Devika 1. Writing assignments by feature
- Assigned doc owners for remaining functional specs.
- AI - Paul: Propagate assignments to spec wiki page.
\
2. Feature documentation plan template
- Discussed the template and the responsibilities of feature owners.
- Feature owners write the doc plan for the feature by filling out the template.
- Goal is to identify all changes that need to made for all doc types/information pieces for a particular feature (books, online help, man pages, etc.), and also to identify who's responsible for those changes and who's actually going to do the work.
- Feature owners schedule and manage the task analysis process for their feature(s).
- Discussed template sections:
- People and Roles: Feature owners should just add their own names for now; add additional lines/roles as needed.
- Audience: Administrators, developers, deployers, end users, etc.
- Summary of the Feature From a User's Perspective: Brief, high-level summary of how users will use the feature, for example: This feature enables users to deploy scripted applications in the application server.
- Statement of Work: Describes in detail all work that needs to done as it relates to the new feature – which information piece, who's going to do the work, etc. Feature owners are responsible for tracking down all places where changes need to be made, working with other writers if necessary to identify those places and impacts (i.e., where/how a guide might be affected). The impact rating system is somewhat subjective; if you need to rewrite everything, that would probably be Major; if you need to add one option or do something simple, that would probably be Minor; Paul will try to lead off with one or two of these so we have an example of what he had in mind when he created the template.
- Review Schedule: This reflects the review schedule for all information pieces affected by the feature; reviews are not just done at the book-level.
- Discussed next steps:
- Book owners still need to be assigned, but if possible book owners will stay the same as they were for Prelude (with the exception of the online help).
- Need to decide how to handle features that are being brought forward from v2 but that weren't in Prelude.
- Other:
- Somewhere in the template there should a place to record for which distro(s) the feature is available by default.
- Topics need to include information about what you need to have/get to use the feature, i.e., have a certain distro, download something from the update center, install an add-on component, etc.
\
3. Other business
\
Update from Paul regarding suspended AI: "Determine whether the modularity of GlassFish v3 necessitates modular documentation for GlassFish v3."
- Starting to record ideas about how to handle this for different distros; will use that as the basis for future discussions.
- For bundled docs, specifically online help – whether online help will be modular will be determined by the technology and whether engineering can find a way to merge modular help sets at runtime.
- For the unbundled docs, options include the following (Paul's identifying pros and cons for each):
- One doc set per distro (like old EE, PE days); users of a particular distro are sent to a particular place and get docs for just that distro. Potential issue: What if a user has an install that's in some kind of intermediate state, halfway between distros? Where do they go for information?
- One doc set, where we retain the existing structure of the guides but subdivide the topics in a guide by distro.
- One doc set, but split the individual docs (follow the Java EE 6 tutorial model); for example, one Admin Guide for the Classic distro and one for the Web distro.
- There are various questions, including how to handle the docs that we deliver through the IPS tool.
\
4. Next meeting
- Thursday 01/08/09 2-3 PM PST – No meetings 12/25/08 and 01/01/09
\
Main meetings page
|
