Taking Stock of Docs: What Worked and What Didn't?

The end of the year is a good time to take stock: What worked, what didn't, what to focus on going forward.

The Application Server docs team tried some new things this past year and we'd like to know how you, our customers and documentation consumers, feel about them: What worked and what didn't?

A few items to consider:

  • Documentation Comments Wiki – Do you know about it? Did you use it? Was it helpful? The doc comments wiki is a great mechanism for providing feedback on the docs (and now we'd like feedback on the feedback mechanism!).

  • User and Developer FAQs – Did you use or contribute to either of these? Are they helpful? What would make them better? These FAQs are definitely a community effort, so if you have something to contribute, please do.

  • Documentation Mailing List – Are you on it? If not, why not join? If you're interested in documentation and in building the documentation community, this is great place to get the conversation started. You can join the list from the GlassFish mailing lists page. The page isn't in alphabetical order so you'll need to scroll way down (the java.net infrastructure apparently orders the list based on age, oldest to newest).

  • Documentation Planning Meetings – Now is the time to plan for Application Server 10 / GlassFish v3 and we need your input! We've been holding a series of informal planning meetings to which the community has been invited but so far it's been just us doc folks. Are you aware of these meetings? What's been stopping you from attending? What would make it more likely that you'd attend and get involved (different topics, different time, more advance notice, clearer understanding of what's being asked of you)? What would you like to see for docs? How should they be developed and delivered? So many questions! These planning meetings will start up again in January. Details can be found on the meetings page. Please join us!

That's just a sampling of what's been happening in the wonderful world of Application Server docs this past year (in addition to providing complete documentation sets for the Application Server 9.1 / GlassFish v2 and Application Server 9.1 Update 1 / GlassFish v2 UR1 releases!). So to ask the question again: What worked and what didn't? We'd love to hear your answer to that question and to the questions asked in the points above. Please leave a comment here or contact the doc team through the documentation mailing list. We'll be out for the holiday break but will respond to any and all comments when we get back, refreshed and rejuvenated. Thanks in advance, and happy holidays to anyone celebrating them right about now!

Comments:

I am new to the AppServer/JMS world. My struggles finding the next level of documentation for JMS and the related App Server documentation was next to maddening. I worked my way up from Java SDK 1.3 (the listed Tutorial on Sun's Web site) which referred to only the command line access to asadmin. I did then find the link to the Java SDK1.4 tutorial which also had the introduction to the App Server (not yet listed as Glassfish), but setup in the code/app server (CLI vs. Admin Console) was still confusing - the mix between command line and AppServer use. When I finally got to the Java SDK 1.5 (and 1.6) I find later information on actual coding and the App Server setup. Even currently (as I am writing this) I am using the Application Server 9.1 Development Guide (819-3672) which refers to Java SDK 1.4 (I am using the Java SDK 1.5 and the JMS tutorial found in JAVA EE 5). I have seen there is a very distinct difference between coding for JMS and the AppServer using the Java 1.4 and Java 1.5 SDK's.

I would like documentation that on any given step that clearly specifies 'this is command line', 'this is Admin Console', 'this is for Java 1.4', 'this is for Java 1.5', 'this works the same for Java 1.4 and 1.5', etc.

Also, as I am working between 'The Java EE 5 Tutorial: For Sun Java System Application Server 9.1' learning how to use JMS and reading the 'Sun Java System Application Server 9.1 Developer's Guide' I find that the Java EE Tutorial has very clear coding examples (Chapter 31 The Java Message Service API) to which the Application Server 9.1 Developer's Guide refers (Chapter 11 Developing Java Clients -> To Access a JMS Resource From An Application Client - 1 Create a JMS client). The next steps for accessing the JMS Resource are difficult for me to follow being new to this area of using the Application Server.

I realize the Developer's Guide may of necessity be of a higher level than that of the EE 5 Tutorial, but it would be more helpful at a similar level. I have used the forums and find that just a little clarification helped immensely.

I know I have spoken of a small area of all that is available in the App Server, Glassfish in particular (basically only indirectly referred to as AppServer 9.1 or AppServer), but I hope my observations and struggles will help.

Posted by Richard D Blaha on December 31, 2007 at 12:26 AM PST #

Richard, thanks for the feedback. Sorry it was so frustrating for you to find the info that you needed, and that it meant doubling back on the docs due to version problems.

While I can't directly address all the specific problems you had, I can maybe provide some overall context to our docs so it makes a little more sense.

As you noted, there is a significant difference in coding practices when using the Java EE 5 APIs (including JMS) compared to the previous J2EE 1.4 and 1.3 APIs. The goal with Java EE 5 was to simplify the process of developing server-side Java applications. For a beginner to this world, starting off with the Java EE 5 Tutorial is the best way to learn how to use JMS and the other Java EE APIs. It's too bad you started off looking at the J2EE 1.3 and 1.4 docs, and on behalf of Sun, I apologize we didn't organize the information better so you began with the simplest and most up-to-date version of the software.

The Application Server 9.x/GlassFish 2.x Developer's Guide is intended as a companion document to the Java EE 5 Tutorial, and covers procedures that are specific to Application Server/GlassFish. That is, Application Server/GlassFish is an implementation of a Java EE 5 server, so anything that is unique to Application Server/GlassFish (configuration, deployment, etc.) is covered in the Developer's Guide and the other books in the documentation set. In this case, it would break the organization of our docs to put JMS code examples in the Developer's Guide, as JMS is a standard Java EE API.

Posted by Ian Evans on January 07, 2008 at 07:15 AM PST #

Hi Richard - Just wanted to echo Ian's response and say thanks for your feedback and sorry for your frustration! There's definitely room for improvement and your comments will help us get there. Thanks for taking the time to provide them.

Ian explained the general landscape of Java EE development and how the docs are organized. Hopefully that helped a bit. Regarding your specific suggestions, such as labeling procedures based on how they're used, your points are well taken and will be factored in as we plan for the next major release of GlassFish/Application Server (GlassFish v3/Application Server 10). Everything's on the table, including a complete revamp/reorganization of the docs. As mentioned in the blog post, that planning is currently underway and we'd love to have your continued input. The best way to improve the docs is to hear from people like you who use them (or try to!).

Thanks again for the feedback. Please let us know if other issues arise or if you have any other thoughts.

Posted by Gail Risdal on January 09, 2008 at 05:37 AM PST #

Allow FishCAT member to use IssueTracker to log review comments is a big plus. Hope we can expend this option to others since using wiki to input review comment is not very user friendly, at the begining it also required community sign SCA first, not sure if this rule has been waved now, also wiki tends to be slow and some time goes down in other part of world, we got many input from community of running into issues using wiki to input the review comments. I hope doc team can consider the community input and make it easier for community to provide their review comments by using the issuetracker which is the tool they used often and are good at. This will encourage a better review. Thanks, Judy

Posted by Judy Tang on December 11, 2008 at 09:43 AM PST #

http://docs.sun.com/app/docs/coll/1343.7

Above is GlassFish v3 prelude doc link, it is not easy to remember since it has the number 1343.7. Is there some way we can get http://docs.sun.com/app/docs/glassfish/version_number
where the version_number can be changed, this way it is easy for user to remember the link and find the right doc ?

Just wondering if user do not remember the link, can user find out doc easily ?

Thanks,
Judy

Posted by Judy Tang on December 11, 2008 at 09:47 AM PST #

Thanks for your feedback, Judy!

Regarding your first comment about using Issue Tracker for reviews and comments instead of the Doc Comments Wiki: An SCA is not required for the comments wiki; contributions are governed by the wiki Terms Of Use. While our first preference is that reviewers provide comments on the comment wiki pages, it's fine to use Issue Tracker, too. Whatever works best for individual reviewers. The testing and reviews done by the FishCAT members is extremely valuable, and we certainly don't want to make it hard for people to participate!

Regarding your second comment about URLs for doc collections: You're right! The numerical doc collection ID (i.e., 1343.7) isn't very user friendly and easy to remember. Unfortunately, that's a constraint of docs.sun.com. Your point is well taken, however, and will be passed along.

Posted by guest on December 15, 2008 at 08:54 AM PST #

Hi,
I am working with JEE6 / glassfish V3 release. I would like to know if there are any specific material on how interceptors, decorators, interception binding, bean qualifiers are expected to work with class/methods with typed parameters (Generics).
I also feel that this should be available as part of the corresponding JSRs.

Thanks
Raghavan

Posted by Raghavan on January 28, 2010 at 04:01 PM PST #

Post a Comment:
Comments are closed for this entry.
About

The scoop on GlassFish documentation and more!

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today