GlassFish - World's first Java EE 7 Application Server


GlassFish v3 Documentation Planning Minutes - 6/05/08

Main meetings page

Attendees

Paul, Gail, Jennifer, June, Hanan, Dixie, Alan
\

Agenda

  1. Review of AIs - Paul
  2. Status of Glass Fish v3 User Task Analyses - Paul
  3. Status of deliverables
  4. Quality improvement measures for the v3 doc set
  5. Open mic - All
  6. Next meeting - All
    \

Meeting Notes

1. Review of AIs - Paul

    • Paul:* Find out if TP2 is going to be turned into an FCS-quality developer release. DONE - Yes
    • Paul:* Start a SolBook rules page. DONE
    • June and others:* Contribute to the SolBook rules page. CAN NOW BE STARTED
    • Paul:* Create a wiki page and add ideas to it for quality improvement measures for the v3 doc set. DONE
  • Paul: Look at list of new features and propagate into the Glass Fish v3 User Task Analyses table. NOT STARTED
  • Book owners: Look through your books, identify task brainstorming sessions that would affect your books and update the wiki page accordingly. IN PROGRESS - Additional discussion about the table, creating pages for each book, etc. For now, leave this as one page and populate the table with any new TA sessions you have scheduled (add them at the top, so they're visible); we'll reconsider this in the future and possibly treat the main TA page as a landing page that then points to individual book pages.
    • Book owners:* Add a link from each task in the task analysis page to the explanation of the task in the doc set.
      If the task isn't going to be doc'd because it's out of scope, mark it as such; if the task is something we're going to doc but just haven't gotten to yet, leave as-is; we'll assess later whether items should be moved to the Community Docs wish list. IN PROGRESS - June is done; Jennifer and Debbie are in progress
      \

2. Status of Glass Fish v3 User Task Analyses - Paul
Covered under discussion of the action items
\

3. Status of deliverables:

    • Paul:* Installation instructions for TP2 Refresh are in progress; incorporating comments, pursuing additional information, waiting on JDK info
    • June:* Added two new chapters and EJB info to Dev Guide
      \

4. Quality improvement measures for the v3 doc set
Paul put together a page with some ideas, designed to stimulate discussion; much discussion about the page:

  • What does "options are fully explained" mean? Paul will change this to read "command options in man pages are fully explained" - this is just one area where the docs fall short and a quality issue has been called to our attention; if there are command options, it's not sufficient to just list the choices, you need to explain what the choice entails, why you'd want to choose it, what happens when you do, etc.; don't just list the option without any explanatory text
  • If there's a default, it should always be stated; what about placement?; the general consensus is that you should put it at the end
  • It would be helpful to have links to the Solaris man page guidelines; AI - Paul: Find the pointer to these guidelines and send it to the appropriate alias (not sure if they're inside or outside of the firewall)
  • Question about inline formatting of index terms; consensus: either follow or don't follow them consistently - don't have a mix; hardly anyone currently uses the inlines in the index; writers consider it desirable, but it's not a high priority
  • We can implement the inline guidelines in new content, but what about going back and fixing existing content? What about all of the incorrect inline elements in existing books? It's a judgement call - prioritize fixes based on the biggest/most noticeable impact to doc users; emphasis tags are one big area for improvement (text shows up bold when it should show up italicized; differences in online versus PDF versions of the doc, etc.)
    • Summary/AIs:* Paul will make changes to the page as discussed in the meeting; if you have things to add to the page, please do so; if you discover other issues with existing docs, send mail to Paul (with a URL if possible), so he can start keeping a running list of issues/areas for improvement
      \

5. Open mic - All

  • Question about page 117 in the style guide ("write meaningful text") - discussion about what should/should not be inside the screen element (long discussion; listen to recording for full details)
  • Question about where/when to use replaceable values; not mentioned in the style guide; if you can't use replaceable values in the examples, where can you use them? Answer: Synopsis portion of a man page; instructions in a step in a procedure, i.e., difference between "here's what you must type, some of which you provide your own values for" (which includes replaceable values), versus "here's something I'm showing you for illustration" (which doesn't include replaceable values). Examples turn abstract replaceable stuff into something that is concrete; the point is to make it concrete and give people an idea of what the thing would actually look like in the real world
    \

6. Next meeting - All
Thursday 6/12 2-3 PM PDT
\

Main meetings page