<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
</head>
<body bgcolor="#ffffff" text="#000000">
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.<br>
<br>
<br>
<span class="Apple-style-span" style="border-collapse: separate;
color: rgb(0, 0, 0); font-family: 'Times New Roman'; font-size:
16px; font-style: normal; font-variant: normal; font-weight:
normal; letter-spacing: normal; line-height: normal; orphans: 2;
text-indent: 0px; text-transform: none; white-space: normal;
widows: 2; word-spacing: 0px;"><span class="Apple-style-span"
style="color: rgb(51, 51, 51); font-family: 'Lucida
Grande',Arial,Helvetica,sans-serif; font-size: 12px; text-align:
left;">
<h3 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.5556em;
background-color: transparent; font-weight: bold;">Tasks</h3>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Tasks are
good.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Be direct
and concise. Tell the reader what they need to know to do what
they need to do, and no more.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Instead of:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Use:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">Use the Lilliput class to change the widgets on
the webpage. [<em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Lead in to a procedure</em>]</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">or</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">The Liliput class is used to change the widgets
on a webpage. [<em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Incidental contextual
information, where the Liliput class is related to what
follows, but is not the main focus</em>]</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Why:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">The goal is to decrease the reader's uncertainty
and increase their sense of mastery of the material and their
practical effectiveness.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Elaborate
in the right place - use a "progressive reveal" to avoid
information overload.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Instead of:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Use:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">Turn on the computer. For further information
refer to <appendix one>.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Annotated
examples are awesome.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Address the
most common use case first. Deal with edge cases afterward.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;"><em style="margin: 0px;
padding: 0px; border-width: 0px; outline-width: 0px;
font-size: 13px; background-color: transparent;"><br>
</em></strong></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Instead of:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;"><em style="margin: 0px;
padding: 0px; border-width: 0px; outline-width: 0px;
font-size: 13px; background-color: transparent;">Procedure:
Booting the computer from the network</em></strong></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">1.</strong><span
class="Apple-converted-space"> </span>Turn on the computer.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">2.</strong><span
class="Apple-converted-space"> </span>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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">3.</strong><span
class="Apple-converted-space"> </span>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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Use:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;"><em style="margin: 0px;
padding: 0px; border-width: 0px; outline-width: 0px;
font-size: 13px; background-color: transparent;">Procedure:
Booting the computer from the network</em></strong></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">1.</strong><span
class="Apple-converted-space"> </span>Turn on the computer.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">2.</strong><span
class="Apple-converted-space"> </span>Press the<span
class="Apple-converted-space"> </span><strong style="margin:
0px; padding: 0px; border-width: 0px; outline-width: 0px;
font-size: 13px; background-color: transparent;">F12</strong><span
class="Apple-converted-space"> </span>key when prompted.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"> <span class="Apple-converted-space"> </span><strong
style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 13px; background-color:
transparent;">Result:</strong><span
class="Apple-converted-space"> </span>The boot options menu
appears.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">3.</strong><span
class="Apple-converted-space"> </span>Choose the PXE boot
option.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"> <span class="Apple-converted-space"> </span><strong
style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 13px; background-color:
transparent;">Result:</strong><span
class="Apple-converted-space"> </span>The computer boots
from the network.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><Appendix three> describes further boot
options.</p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Screenshots
are good from the end-user perspective, but if you want<br>
to use them, you need to commit to keeping them up to date.
There is<br>
nothing more useless than an out-of-date screenshot.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h3 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.5556em;
background-color: transparent; font-weight: bold;">Concepts</h3>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;"><br>
The goal of documentation is to decrease uncertainty.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Instead of:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Use:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">The sky is blue because of reflection from water
on the Earth's surface.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Reduce
uncertainty. Avoid "should", "may", "must".</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Instead of:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Use:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">Take shelter under a stable structure if caught
in a storm. Avoid low-lying areas prone to flooding.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Don't get
caught up in how awesome your implementation is. The<br>
customer is already convinced, since they are trying to use
it.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">Here is a paragraph from the Weld documentation:</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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!</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">This sentence loses nothing if the last sentence
is removed, and you will gain more credibility by being
understated.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Do not rant.</strong></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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".</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">This entire paragraph can be removed from the
text without losing anything.</p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Introduce a
new word in context, then explain what it means:</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">"You control widgets with sprockets. Sprockets
are imaginary things made in<br>
factories."</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Use lists,
tables, variablelists and other visual cues to assist
information assimilation.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">Here as an example of a place where a list eases
readability, from the CXF User Guide.</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Instead of:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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).</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><em style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">Use:</em></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">CXF supports a variety of web service standards
including:</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- SOAP</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- The WS-I Basic Profile</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WSDL</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-Addressing</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-Policy</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-ReliableMessaging</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-Security</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-SecurityPolicy</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-SecureConversation</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">- WS-Trust (partial).</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Guided use
case examples that increase in complexity are a good way to
progressively introduce features.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">See the JBoss Microcontainer Guide for an
example, available here:<span class="Apple-converted-space"> </span><a
class="jive-link-external-small"
href="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/JBoss_Microcontainer_User_Guide/index.html"
style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 13px; background-color:
transparent; color: rgb(53, 84, 145); text-decoration:
none;">http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/JBoss_Microcontainer_User_Guide/index.html</a></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<h6 style="margin: 0px; padding: 10px 0px 4px; border-width:
0px; outline-width: 0px; font-size: 1.1111em;
background-color: transparent; font-weight: bold;">Real world
examples help the reader relate abstract concepts to the their
real-world problem space.</h6>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;">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:</p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<div id="_mcePaste" style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 12px;
background-color: transparent;"><span style="margin: 0px;
padding: 0px; border-width: 0px; outline-width: 0px;
font-size: 12px; background-color: transparent;
text-decoration: underline;">An Evening On the Town</span></div>
<div id="_mcePaste" style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 12px;
background-color: transparent;">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.</div>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent; min-height: 8pt; height: 8pt;"> </p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><strong style="margin: 0px; padding: 0px;
border-width: 0px; outline-width: 0px; font-size: 13px;
background-color: transparent;">References</strong></p>
<p style="margin: 0px; padding: 0px; border-width: 0px;
outline-width: 0px; font-size: 10pt; background-color:
transparent;"><br>
Hopefully, most of the references are in your Javadoc, where
developers expect to find them.<br>
References for command-line tools should really be in their
--help option.<br>
Hopefully, users don't have to look in documentation for
reference material at all.<br>
If they do, make it useful and intuitive to navigate. Tables,
lists, etc.</p>
</span></span><br>
</body>
</html>