[seam-dev] The docs your docs could be

[Jason Porter]

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 at redhat.com> wrote:
> 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.
>
> _______________________________________________
> seam-dev mailing list
> seam-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/seam-dev
>
>



-- 
Jason Porter
http://lightguard-jp.blogspot.com
http://twitter.com/lightguardjp

Software Engineer
Open Source Advocate

PGP key id: 926CCFF5
PGP key available at: keyserver.net, pgp.mit.edu