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 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 procedure/]
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 information overload.
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.
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
*/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
*/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
to use them, you need to commit to keeping them up to date.
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",
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
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
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 assimilation.
Here as an example of a place where a list eases readability, from the
CXF User Guide.
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 distribution.
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.