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 <[email protected]> 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 > [email protected] > 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 _______________________________________________ seam-dev mailing list [email protected] https://lists.jboss.org/mailman/listinfo/seam-dev
