GlassFish v3 Documentation Planning Minutes - 11/14/07

Attendees

Alan, June, Debbie, Mike, Jennifer, Gail, Paul, Ian, Rajeev

Agenda

• Documentation content and organization – What should GF v3 docs look like?
• Community involvement – How to best involve the community in content creation and contribution?

Discussion Summary

Brief recap of previous discussions:

• Discussing GF v3 docs, focusing on ways to involve the community and on doc architecture

• Identified 4 potential tiers/models for producing docs and involving the community:

1. Implement a wiki sandbox/area where the GlassFish doc team and the GlassFish community can all contribute. Typical docs contributed for this model would include things like FAQs, short HowTo docs, articles, etc. The User FAQ already falls into this category.
2. Select a subset of manuals in the doc set; convert those entire manuals to wiki format and post them on GlassFish wiki; the community can then edit them. This was done to some extent for GF v1 and v2 (for example, the Error Message Reference was converted and posted on the wiki).
3. Publish the docs in some non-editable format in HTML but allow the community to append comments to the docs. NOTE: While this model is preferable in many ways, this option is not currently possible due to tools limitations.
4. Adopt a model that's closer to true open source, such as what Open Solaris is doing with its documentation project; make the documentation source files available to the community (probably convert to SolBook XML), and enable community members to download, modify, redistribute, contribute, etc. (per terms of use/legal guidelines). Doc team would work with contributing community members to get appropriate changes into the commercially branded documentation.

• Why 4 models/tiers? There are several goals of involving the community, not all of which can be achieved through the same mechanism; want to make it as easy as possible for people to participate.

• For the near term, will still use the doc comments wiki

• Doc set hasn't changed in a long while; essentially the same doc set since App Server 8; that's one reason it's time to reassess, but another question is: does the doc set lend itself to community contribution?

The following ideas emerged during previous discussions about GF v3 docs:

• Look further into the idea of task-based documentation (do a more formal/informal task analysis)

• Use a task roadmap or roadmaps; provide some kind of roadmap that categorizes or somehow makes sense of the tasks we're providing

• Have a wish list where we more or less explicitly let the commmunity know which topics could use help

• Reduce redundancy; topics covered in several places in the docs and could/should be consolidated

• Improve Search; look into ways to make it easier to search our docs through whatever mechanism GF community members may be using
  Wrapped up recap - started new discussion about doc architecture for GF v3 docs:

• How do we get to the appropriate doc architecture for the GF v3 release? Is it too early to do that? Many design decisions are still being made. Architecture of GF v3 changing rapidly - not sure how much of the v2 stuff will be carried forward.

Discussed doing a task analysis:

• In general, it's a great idea but there's still going to be a need for man pages, Javadocs, developer reference docs, etc.; those docs will still be produced; the discussion about the task-based approach is more appropriate for the guides; let's do a task-based analysis and see if we can implement a more task-based approach for GF v3 (group agreed)

• How do we implement that?

• What about rapid task analysis (RTA)? That's a good approach for these types of things.

• Will this work for three primary audiences: developers, users, administrators?

• Yes, task analysis applies to all three groups; could solicit tips and sample apps from the community

• Yes, because of what the individual roles are doing. A lot of uses/users span all of these roles. You might be performing admin tasks if you're a developer because you need to be able to create/develop something, etc.

• Some tasks are really hard to categorize, re: creating a custom realm; realms is an admin task; customizing anything is more of a dev function

• Perhaps that's where these task roadmaps come into play; is task analysis something we can do ourselves?

• Maybe as an intial pass, but we'll want to involve SMEs/community members
  Next steps:

• Explore RTA; determine what's involved; perhaps make proposals/presos about task-based approach in the appropriate meeting/forum

• Get up to speed on what's planned for GF v3

• Determine date for next discussion; post on the meeting page

Community Comments and Suggestions?

Any thoughts about this discussion? About GlassFish v3 docs? Please join the conversation! You can do that in several ways:

• Add your comments to this wiki page
• Participate in these discussions; details are posted on the GlassFish v3 docs meeting page
• Use the [docs@glassfish.java.net] mailing list

Documentation is a community effort, and contributions can be small or large, from writing a HowTo topic to collaborating on a larger guide. If you're interested in docs, we'd love to hear from you.