This looks like a great addition to put up on the Modules site for any
one in the community that wishes to create their own module.
On Fri, Jan 21, 2011 at 03:48, Shane Bryzak <sbryzak(a)redhat.com> wrote:
I asked Rebecca Newton, one of the experts on our docs team if she
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 are good.
Be direct and concise. Tell the reader what they need to know to do what
they need to do, and no more.
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 the Lilliput class to change the widgets on the webpage. [Lead in to a
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]
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
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
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.
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
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.
The goal of documentation is to decrease uncertainty.
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.
The sky is blue because of reflection from water on the Earth's surface.
Reduce uncertainty. Avoid "should", "may", "must".
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.
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
Use lists, tables, variablelists and other visual cues to assist information
Here as an example of a place where a list eases readability, from the CXF
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
CXF supports a variety of web service standards including:
- The WS-I Basic Profile
- 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
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
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
If they do, make it useful and intuitive to navigate. Tables, lists, etc.
seam-dev mailing list
Open Source Advocate
PGP key id: 926CCFF5
PGP key available at: