[seam-dev] The docs your docs could be

[Shane Bryzak]

I asked Rebecca Newton, one of the experts on our docs team if she could 
put together a list of tips for us to follow when writing reference 
documentation for the Seam modules.  I think she's done an awesome job, 
and produced an excellent guide which all of the module leads should 
read carefully and try to incorporate into their documentation-writing 
style.  I've copied the guide below, which I hope everyone finds 
useful.  If you have any additional documentation-related questions 
(including any related to documentation styling) please let me know and 
I'll forward them on.


      Tasks


            Tasks are good.


            Be direct and concise. Tell the reader what they need to
            know to do what they need to do, and no more.

/Instead of:/

This class is named after my great uncle who enjoyed Gulliver's Travels. 
His favourite story was the Lilliputians, because he thought that little 
people could do great things, despite how small they were. This is only 
a small class, but it does great things. You can use it to change the 
display of the widgets on the webpage.

/Use:/

Use the Lilliput class to change the widgets on the webpage. [/Lead in 
to a procedure/]

/or/

The Liliput class is used to change the widgets on a webpage. 
[/Incidental contextual information, where the Liliput class is related 
to what follows, but is not the main focus/]

/Why:/

Readers approach documentation from a place of uncertainty and 
confusion. They are looking for clarity and direction. Documentation 
that presents multiple streams of thought and excessive amounts of 
information quickly overloads the reader, and increases their sense of 
confusion and uncertainty. Giving the reader the information necessary, 
in clearly defined and digestible chunks, allows the reader to have a 
"mastery experience". A mastery experience is where the reader goes from 
a state of uncertainty to a state of increased certainty and knowledge. 
This state change creates positive feedback, which increases a reader's 
ability to digest more information. If the reader is overwhelmed with 
too much information their ability to assimilate new information decreases.

The goal is to decrease the reader's uncertainty and increase their 
sense of mastery of the material and their practical effectiveness.


            Elaborate in the right place - use a "progressive reveal" to
            avoid information overload.

/Instead of:/

You will need to turn on the computer. You will need to do this by 
pressing the 'On' button. This will send power to the necessary circuits 
and start the code that will make the computer run. It has lots of 
different parts -- including memory, a hard disk, a modem, and more -- 
that work together. "General purpose" means that you can do many 
different things with a PC. You can use it to type documents, send 
e-mail, browse the Internet and play games.

/Use:/

Turn on the computer. For further information refer to <appendix one>.


            Annotated examples are awesome.


            Address the most common use case first. Deal with edge cases
            afterward.

*/
/*

/Instead of:/

*/Procedure: Booting the computer from the network/*

*1.*Turn on the computer.

*2.*Continuously press F12. On some computers, there is a different 
button you can press. This button will probably be located on the front 
of the keyboard device. On the T500 Thinkpad, you can use the 
ThinkVantage button. This is located to the left of the keyboard.

*3.*A boot options menu will present. Choose the PXE boot option. You 
can sometimes choose some of the options if you are confident in 
installing Fedora.

/Use:/

*/Procedure: Booting the computer from the network/*

*1.*Turn on the computer.

*2.*Press the*F12*key when prompted.

*Result:*The boot options menu appears.

*3.*Choose the PXE boot option.

*Result:*The computer boots from the network.

<Appendix three> describes further boot options.


            Screenshots are good from the end-user perspective, but if
            you want
            to use them, you need to commit to keeping them up to date.
            There is
            nothing more useless than an out-of-date screenshot.


      Concepts



            The goal of documentation is to decrease uncertainty.

/Instead of:/

The sky is a reflection of light off the water. This creates a blue hue 
that has been described as blue, baby blue, powder blue, and others, but 
can look different depending upon the weather and other environmental 
factors. It may also appear a different shade of blue depending upon a 
person's individual perception of that colour. Blue is made up of 
different colours, which are all part of the colour wheel.

/Use:/

The sky is blue because of reflection from water on the Earth's surface.


            Reduce uncertainty. Avoid "should", "may", "must".

/Instead of:/

If you are caught in a storm, you may want to take shelter. You must not 
shelter under a tree, or this could fall on you. You should take shelter 
under a steady cover such as a house or awning.

/Use:/

Take shelter under a stable structure if caught in a storm. Avoid 
low-lying areas prone to flooding.


            Don't get caught up in how awesome your implementation is. The
            customer is already convinced, since they are trying to use it.

Here is a paragraph from the Weld documentation:

The reason the same artifact can be deployed to both JBoss AS and 
GlassFish, without any modifications, is because of all the features 
being used are part of the standard platform. And what a capable 
platform it has become!

This sentence loses nothing if the last sentence is removed, and you 
will gain more credibility by being understated.

*Do not rant.*

On the other hand, don't be scared to use session beans just because 
you've heard your friends say they're "heavyweight". It's nothing more 
than superstition to think that something is "heavier" just because it's 
hosted natively within the Java EE container, instead of by a 
proprietary bean container or dependency injection framework that runs 
as an additional layer of obfuscation. And as a general principle, you 
should be skeptical of folks who use vaguely defined terminology like 
"heavyweight".

This entire paragraph can be removed from the text without losing anything.


            Introduce a new word in context, then explain what it means:

"You control widgets with sprockets. Sprockets are imaginary things made in
factories."


            Use lists, tables, variablelists and other visual cues to
            assist information assimilation.

Here as an example of a place where a list eases readability, from the 
CXF User Guide.

/Instead of:/

CXF supports a variety of web service standards including SOAP, the WS-I 
Basic Profile, WSDL, WS-Addressing, WS-Policy, WS-ReliableMessaging, 
WS-Security, WS-SecurityPolicy, WS-SecureConverstation, and WS-Trust 
(partial).

/Use:/

CXF supports a variety of web service standards including:

- SOAP

- The WS-I Basic Profile

- WSDL

- WS-Addressing

- WS-Policy

- WS-ReliableMessaging

- WS-Security

- WS-SecurityPolicy

- WS-SecureConversation

- WS-Trust (partial).


            Guided use case examples that increase in complexity are a
            good way to progressively introduce features.

See the JBoss Microcontainer Guide for an example, available 
here:http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/JBoss_Microcontainer_User_Guide/index.html


            Real world examples help the reader relate abstract concepts
            to the their real-world problem space.

They don't have to be as involved as a full scenario as above, but small 
case studies help more than, "Do this to configure your network." Here 
is an example of a smaller real world scenario from the 
Transactions_XTS_Administration_And_Development_Guide for EAP 6:

An Evening On the Town
The application [in question] allows a user to plan a social evening. 
This application is responsible for reserving a table at a restaurant, 
and reserving tickets to a show. Both activities are paid for using a 
credit card. In this example, each service represents exposed Web 
Services provided by different service providers. XTS is used to envelop 
the interactions between the theater and restaurant services into a 
single (potentially) long-running business transaction. The business 
transaction must insure that seats are reserved both at the restaurant 
and the theater. If one event fails the user has the ability to decline 
both events, thus returning both services back to their original state. 
If both events are successful, the user's credit card is charged and 
both seats are booked. As you may expect, the interaction between the 
services must be controlled in a reliable manner over a period of time. 
In addition, management must span several third-party services that are 
remotely deployed. Without the backing of a transaction, an undesirable 
outcome may occur. For example, the user credit card may be charged, 
even if one or both of the bookings fail. This example describes the 
situations where XTS excels at supporting business processes across 
multiple enterprises. This example is further refined throughout this 
guide, and appears as a standard demonstrator (including source code) 
with the XTS distribution.

*References*


Hopefully, most of the references are in your Javadoc, where developers 
expect to find them.
References for command-line tools should really be in their --help option.
Hopefully, users don't have to look in documentation for reference 
material at all.
If they do, make it useful and intuitive to navigate. Tables, lists, etc.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/seam-dev/attachments/20110121/eb27553a/attachment-0001.html