GlassFish - World's first Java EE 7 Application Server


GlassFish v3 Documentation Planning Minutes - 3/13/08

Main meetings page

Attendees

June, Gail, Dixie, Ian, Paul, Abhijit

Agenda

  1. Usage scenarios for TP2 - Abhijit Kumar
  2. Review of AIs - Paul
      • Paul:* Start a SolBook rules page.
      • June and others:* Contribute to the SolBook rules page.
      • Paul:* Change the description of the process so that it highlights that you also need to identify where the tasks will be documented.
  3. Status of Glass Fish v3 User Task Analyses - Paul
  4. Status of deliverables:
    • Release Notes - Paul
    • Admin Console GUI online help - Paul
    • Man Pages - Paul
    • Administration Guide - Dixie
    • Developer's Guide - June
    • Application Deployment Guide -June
    • Administration Reference - June
  5. Open mic - All
  6. Next meeting - All

Materials

Meeting Notes

1. Usage scenarios for TP2 - Abhijit Kumar

  • TP2 (Technology Preview 2) is developer-focused; we need developer-focused docs for TP2
  • What are people going to do with TP2? – develop
  • Expect many new developers; need to show them how simple GlassFish is to use
  • The focus is on new users (developers); need to tell them how to get started and provide pointers to new features and things they need to know (make sure everything they need to get started and productive is right at their fingertips)
  • We should focus on a very short Quick Start Guide that gets people from download to doing something productive quickly; this Quick Start Guide is the most important doc for TP2; include new commands that make things simple, etc.
  • Should make developers' lives as simple as possible; provide a roadmap through the tutorial that shows what's working in TP2 and what isn't; Ian: the tutorial is already broken up into parts so it should be easy to devise that roadmap through the material
  • Is the assumption correct that TP2 is the repackaging of the existing release into smaller chunks, and we just need to identify the relevant pieces of the existing docs to migrate forward for TP2?
  • Valid assumption with the exception of Comet and JRuby, those are two new things (we haven't doc'd those as supported); the rest is pretty much the same except that the way you get access to it is different (login page, etc.)
  • TP2 is a subset of the previous version's functionality
  • TP2 will likely become a final developer release in a few months
  • TP2 docs will be published on docs.sun.com
    • AI - Paul:* Identify more detailed high-level usage scenarios for TP2; revise plans for TP2 and run them by Abhijit, Jerome, John, Eduardo
    • AI - Paul:* Follow up with Abhijit and Alan for additional details/high-level vision

Much discussion about other items not directly related to TP2:

  • Modular help / man pages / licensing issues
  • Modular nature of GF v3 and thus modular nature of docs:
    • Want users to have only the documentation for the software they've installed
    • The previous point is more important for people who are extending GF and will want to add their own docs (for instance, if they're extending the GF GUI, adding additional commands/their own help, etc.)
    • Previously we had just one way of extending the server, with GF v3 there will be many ways; where will this info go in the doc set? It's not enough to just add more info to the Lifecycle chapter in the Dev Guide; need to provide docs for users of the product who are using their own modules.

2. Review of AIs - Paul

  • Paul: Start a SolBook rules page. IN PROGRESS
  • June and others: Contribute to the SolBook rules page. BLOCKED BY ABOVE
  • Paul: Change the description of the process so that it highlights that you also need to identify where the tasks will be documented. IN PROGRESS

    3. Status of Glass Fish v3 User Task Analyses - Paul

  • Where should add-on technologies such as JRuby, etc. go in the doc set?
  • Much discussion about this, and about refocusing the task analysis (TA) sessions
  • Is the session scope too broad, and thus we're gathering more items than we should be, items that are out of scope for GF docs?
  • We should evaluate the scope of the sessions and make sure we got it right; session should be specific to GF, for example, not about JRuby as a whole, but about JRuby as it pertains to GF; otherwise we end up with tasks that are out of scope for this particular project
    • AI - facilitators of completed TAs:* For TAs for which we've identified a large number of tasks we're not sure belong in the doc set, go back and refine the outputs from the TA; winnow out tasks that are out of scope per the points above (label as out of scope on the outcome wiki page)
    • AI - facilitators of future TAs:* Reevaluate the scope of the session per the points above

      4. Status of deliverables

  • Release Notes - Paul: Not started
  • Admin Console GUI online help - Paul: Migrated all existing v2 help topics into a smaller helpset for TP2; demonstrated new architecture for the online help to the admin GUI team; favorable response; want to avoid the situation where the user gets help in a page, half of which describes how to get to the page in which they're already working
  • Man Pages - Paul: Done a similar thing: separated out man pages he expects for TP2; cleaning up the tagging, mostly in response to comments on doc wiki; people wanted a better format: option on a line by itself with the description beneath it, indented; now going through and doing that; hopes to have a version done this week and hand off for TP2
  • Administration Guide - Dixie: In from workspace so she can start working on it; she's been analyzing the doc, analyzing what needs to happen for TP2, etc.
  • Developer's Guide - June: Not started
  • Application Deployment Guide - June: Not started
  • Administration Reference - June: Not started

5. Open mic - All

No comments

6. Next meeting - All

Thursday 3/20 4-5 PM PDT
Main meetings page