[seam-dev] The docs your docs could be

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_Platf... 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.