GlassFish - World's first Java EE 7 Application Server


GlassFish v3 Documentation Planning Minutes - 12/05/07

Attendees

Ian, Alan, Paul, Dixie, Rajeev, Gail, Hanan, Jennifer, June

Agenda

  • Read through GlassFish v3 design docs and info and come to the meeting ready to list topic areas for the brainstorming sessions, who should be involved, and how to kick the sessions off

Discussion Summary

  • Current activity: Look at GlassFish v3 Requirements page; pull topic areas from that page (items listed in the first column of the table), then pull task ideas from those high-level topic areas
  • Looking at the first column in the table on the v3 requirements page, it would seem that each topic area (category) might be the subject of each session; each topic area has a list of features (click the link for each in the table)
  • There's only about a dozen categories; most categories seem to have about a dozen features (except admin infrastructure, which is huge and will need to be divided into subcategories)
  • Each feature has a task analysis; each task analysis results in a list of tasks
  • Idea is to take each topic area (category) and come up with a list of tasks: each topic area would be the focus of an individual brainstorming session, during which the list of tasks would be brainstormed and identified
  • As we go through and identify topic areas and associated tasks, we should cross-reference the list we're working with on the v3 requirements page with the information on the v3 distributions page
  • Key participants need to be indentified for each brainstorming session, i.e., SMEs from development engineering, QA, product management, support, usability, and the community
  • Goal would be to keep sessions to 1 hour; come up with an initial timetable for the sessions and adjust that as we see how long these sessions actually take; start the sessions in January
  • Question: Are we doing a task analysis on the entire product or just new functionality in GF v3? Discussed but no definitive conclusion.
  • One thought: If we identify all related tasks in each topic category, we should be able to cover the entire product
  • Look at features in GlassFish and try to identify all of the tasks you can perform with those features; might be in existing product or might be related to new functionality in v3
  • Group identified good candidates for the initial brainstorming sessions, i.e., those topic areas in the left column of the table on the v3 requirements page that have smaller lists of features (again, administration is the exception):
    • Administration (broken into subcategories which are TBD)
    • Application Client Container
    • Deployment
    • Diagnostics
    • High Availability
    • Installer
    • Security
    • Web Services
    • Web Tier
  • The above list of topic areas will be presented to the v3 planning committee; will present proposal and recruit participants for the brainstorm sessions
  • One point: We're creating task-based docs and looking at rearchitecting the entire doc set; we don't want to recreate exactly what we have now: Dev Guide, Admin Guide, etc. based on the feature list
  • Using administration as an example, we should focus on tasks users are actually trying to accomplish (i.e., some kind of goal that has an associated series of tasks or sequence of operations with an end goal in mind) rather than thinking in terms of admin GUI and CLI; don't think in terms of GUI/CLI (console/core) but rather in terms of user goals
  • Don't mistake the method you use to accomplish the task with the task category itself; focus on the goal the user wants to achieve (don't get lost in implementation details, i.e., whether I use the CLI or the GUI to accomplish the task/goal)
  • For instance, if dividing up by the separate categories of admin console and admin core and coming up with a task list for each category, some of the tasks you come up with for admin core would be repeated in admin console; should think of admin in the abstract rather than how it's implemented (i.e., there are differences between the GUI and CLI but the end result/goal is the same)
  • This process could very well mean major changes to the doc set. For instance, will we still have something called the Admin Guide? Don't know! The task analysis will determine what we need; don't want to prejudice the outcome, but start with a clean slate and take it from there; everything's on the table
  • General process:
    • Identify topic areas for brainstorm session (see the preliminary list above)
    • Indentify key participants
    • Provide pre-meeting info to participants to prepare them for the goal of the meeting: What do people do with these features? (tasks)
    • Set a time for the meeting, state the purpose, provide introductory remarks to reinforce the purpose of the meeting, let the ideas flow!

Next Steps

  • Present the proposed topic list to the v3 planning committee
  • Reconvene these doc planning meetings in January to finalize topic list, key participants, meeting timeline, etc.
  • Kick off brainstorming sessions in January
  • Between now and then, raise any issues, suggestions, thoughts, etc. on the [docs@glassfish.java.net] mailing list to keep the discussion going

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.