Page History

It's well-known that a consistent user interface is easier to use. Consistency helps users focus on the task rather than the user interface. Likewise, a consistent documentation style helps users focus on the information, rather than the formatting.

A related goal is to design the documentation so that it is easy to maintain, so that it tends to remain internally consistent with the framework itself.

Do it now. Do it once. Do it well.

Overall, there are three goals for the documentation system.

• Say it all
• Say it once
• Say it well

First, we want the documentation to be both complete and concise. This is job one! The documentation should also be a quick but practical introduction to the framework, so newcomers can get started as easily as possible. To keep people coming back, the documentation should also be a repository of the tips and tricks we use in our own applications, so that people can find it here instead of asking over and over again on the list.

Second, the documentation should be easy to maintain. Ideally, we should cover the detail of each topic once, and draw as much detail from the source code and examples as possible (using the snippet macro).

Third, the documentation should be text-book quality; if not in the first draft, then in the next. Don't hesitate to hack in a new page. Better that we have the page than we don't. (See Job One!) But, as time allows, we should try to make each page the best that it can be. A great many people access the documentation, and it's worth the effort to make the "documentation experience" productive and enjoyable.

Capitalization of common terms

• Java
• Javadoc
• HTML
• XML

General Punctuation and Grammar

Good online resources for punctuation, grammar, and text style include

• Punctuation Made Simple
• Associated Press Style Guide Essentials
• Wikipedia Manual of Style

In print, two excellent (and inexpensive!) resources are

• The Elements of Style
• Associated Press Stylebook

Also excellent, but more expensive:

• Chicago Manual of Style

Quick Tips

• Use as few words as possible. Instead of "but there are some quirks about it" try "but there are quirks".
• If a list of items includes both a term and an explanation, consider using a table instead of bullets.
• Avoid using "This" by itself. Instead of "This lets us" try "This strategy lets us".
  • Ask yourself: "This what?"
• References to other wiki pages can be unqualified. For example: "See Documentation Style Guide."

Don't be smurfy!

A lot of API members use the term "action". We have

• action extensions on pages,
• action attributes in forms,
• action elements in configuration files, and
• Action Java classes, some of which may implement the
• Action interface.

Here are some terms that can be used to help clarify which action is which.

• Use "the framework" or "Struts 2" to refer to the codebase as a whole, including any frameworks we use internally, like XWork and OGNL.
• Use "Action class" or "action handler" to refer to the Java class incorporated by the action element.
• Use "action mapping" to refer to the object created by the action element.

Page Save Comment

Try to include a brief description of a change when saving a page. The comments are included in the page's history. The comments are also included on the daily change report. In a group environment, it's important to help each other follow along.

Parent Pages

Use the Parent Page feature to create a hierarchy of pages. The parent pages are reflected in the "bread crumb" menu. If properly used, parent pages can help browsers "visualize" the documentation as an outline.

The root of the documentation is the "Home" page, which is also the "Welcome" page. The documentation is ordered into three main areas: Tutorials, FAQs, and Guides. Each area has a contents page, whose parent is Home. Other pages within each section can also serve as parents, to help organize the documentation into a coherent outline.

Labels

Pages can be cross-indexed with the Label feature. Labels are not be used much yet, except for internal authoring.

Shortcuts Links

The Shortcut Link feature should be used for any external reference that may be used elsewhere.
Shortcuts being used include

About Headings

This section refers to: Notation Guide >> Headings.

About h1

Don't use h1. at the top of each page. The page title serves as the "top level header". This is not as obvious online, but it is very apparent when the documentation is exported to HTML or PDF.

Try to start each page with some introductory text, to separate the page title from the rest of content.

Likewise, try to have some content between all page headings. Avoid placing headings one after the other.

Document sections

Headings can help you divide your document in sections, subsections, sub-subsections and so forth.

Advantages

Your document becomes more organized.

Disadvantages

Too many headings can fragment the text.

Headings capitalization

Try to use initial capitals for h1 and h2 headers.

For h3 and smaller headings, try to capitalize only the first word, and any proper nouns.

By using different capitalization styles, we emphasize the importance of bigger headings.

Avoid skipping headers

The headers form an outline for the page. When writing term papers, it is not a good practice to skip outline levels. When writing hypertext, it is not a good practice to skip heading levels either. Try not to skip from a h2 to a h4.

More on Text Effects

This section refers to: Notation Guide >> Text Effects.

Text effects like strong, emphasis, and inserted can be used in the usual way to denote important parts of a sentence.

Monospaced should be used to files, tags, and methods, like struts.xml, <xmltag />, and execute. Class and Interface names may be left in normal face, like Action and Interceptor.

A panel should be preferred to a block quote.

The color fonts should be avoided or used only with great care. Some people have difficulty seeing some colors, and the colors may not be apparent if the page is printed.

Text Breaks

This section refers to: Notation Guide >> Text Breaks.

Text breaks should not be used to format blocks on the screen. If there is an issue with the way paragraphs or headings are being rendered, we should customize the stylesheet.

Lists

This section refers to: Notation Guide >> Lists.

Unordered lists should be created only with the * (star) notation.

Ordered list should be used when numbering the items is important. Otherwise, prefer unordered lists.

• This is an unordered list in star notation;
• Items can have sub-items
  • That can have sub-items
    • That can have sub-items ...
      • What is the limit?
• Mixing ordered and unordered lists is possible:
  1. One;
  2. Two;
  3. Three.

Images

This section refers to: Notation Guide >> Images and Notation Guide >> Misc.

Avoid using external images for bullets or icons. Prefer the equivalents provided with Confluence.

Images can be included by URL or annexing the binary to the page. Prefer annexing when possible, since URLs are subject to change.

Always observe copyright issues. Do not annex images unless it an original or public domain work, or the author has donated the image to the foundation.

Example: Image Added

Icons

Use , , , and to bullet important one-liners. Use to highlight cross references.

Used carefully, icons can make the content easier to read and understand.

However, if icons are overused, they lose impact (and can make a page look like a ransom note).

Casual icons like and should be used with care or avoided.

Tables

This section refers to: Notation Guide >> Tables.

Prefer lists for single-value entries. Prefer tables for lists with multiple columns.

Tables are very useful when lists just don't do it. Meaning: don't write a table when a list suffices. Tables are more organized, because you can align the text in columns. Since the markup text for tables in Confluence is not easy to read, complex and big tables can be hard to maintain.

Advanced Formatting

This section refers to: Notation Guide >> Advanced Formatting.

Panels should be used as needed. Try to select the right panel for the content.

Try to give all panels and {code} blocks meaningful titles. People scan the pages looking for likely tips and examples.

Avoid generic titles like "Warning" or "Example". Style the headings like they were h3. or smaller.

When a panel contains a file or a class, the panel title should refer to the filename or classname.

Try to specify the language for {code} blocks.

/** Hello World class. */
public class HelloWorld {
  /** Main method. */
  public static void main(String[] args) {
    System.out.println("Hello, World!");
  }
}

Try to use snippets for code blocks whenever possible!

Avoid tabs in code blocks, use two spaces instead. Long lines should be formatted to fit in a 800x600 resolution screen, without resorting to horizontal scrolling.

A typical example of noformat would be the command line statements to compile and run the code above.

Either the code or noformat block can be used to represent command line windows. The terminal notation ({$}} should be used to represent a system prompt.

$ javac HelloWorld.java

$ java HelloWorld
Hello, World!

Change Happens

Anyone who has worked with databases knows the value of normalizing the schema. Ideally, we want to store each fact exactly once, and then use query system to retrieve that fact whereever it is needed. If we store a fact once, we only need to update it once, and we avoid inconsistencies in our data set.

To the extent possible, we want to "normalize" our technical documentation. Like a database, all technical documentation is subject to change. When change happens, we want the documentation to be as easy to update as possible. One way to do that is to try and minimize redundancy (without sacrificing ease of use).

Single sourcing with snippets

The "holy grail" of technical documentation is single sourcing. One way we try to single-source documentation is to pull content directly from the Javadocs and source code into the documentation.

Using a snippet macro, we are able to tag portions of any file for reuse. The macro fetches those snippets from a repository and merges the content into the documentation.

Example snippet usage

{snippet:id=example|lang=xml|javadoc=true|url=struts2/core/src/main/java/org/apache/struts2/components/If.java}

All snippets are marked off by the pattern START SNIPPET: XXX and END SNIPPET: XXX where XXX is the name of the snippet that is assigned in the id attribute of the macro. The URL is typically a location that points to the project's source control contents. |

About URLs

A URL must start with a valid prefix. There are two types of prefixes:

• com.opensymphony.xwork2. Notice the period. This syntax is better when you want to include content from a class because they allow you to use the fully qualified classname as the URL.
• struts2/ Notice the trailing slash. This syntax better when you want to include content content from non-class files such as xml or properties files. They may also be needed if a class based prefix for a sub-project has not be setup.

To include a snippet from http://svn.apache.org/repos/asf/struts/struts2/trunk/apps/showcase/src/main/java/org/apache/struts2/showcase/DateAction.java the two possible methods are:

{snippet:lang=java|url=struts2/apps/showcase/src/main/java/org/apache/struts2/showcase/DateAction.java}
{snippet:lang=java|url=struts2/apps.showcase.src.main.java.org.apache.struts2.showcase.DateAction}

To include a snippet from https://svn.apache.org/repos/asf/struts/struts2/trunk/xwork-core/src/main/java/com/opensymphony/xwork2/validator/validators/StringLengthFieldValidator.java the two possible methods are:

{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator}
{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/validators/StringLengthFieldValidator.java}

The list of available prefixes:

About snippet markers

When possible, all snippet markers should be in comment blocks. How they are commented depends on where the snippet is being embedded.

<!-- START SNIPPET: xxx -->
...
<!-- END SNIPPET: xxx -->

if (true != false) {
    // START SNIPPET: xxx
    System.out.println("This is some silly code!");
    // END SNIPPET: xxx
}

If the snippet is embedded within Javadoc comments use HTML comments to declare the snippet as they won't render in the Javadocs.

When using the <pre> tag within Javadoc comments embed the snippet markers inside the <pre> tag.

* <pre>
* <!-- START SNIPPET: example -->
* &lt;!-- records only the action's execution time --&gt;
* &lt;action name="someAction" class="com.examples.SomeAction"&gt;
*     &lt;interceptor-ref name="completeStack"/&gt;
*     &lt;interceptor-ref name="timer"/&gt;
*     &lt;result name="success"&gt;good_result.ftl&lt;/result&gt;
* &lt;/action&gt;
* <!-- END SNIPPET: example -->
* </pre>

A <pre> tag within a Javadoc comment would be escaped and rendered as part of the snippet. See TimerInterceptor.java for an complete example.

Back: Contributors Guide

This page contains my suggestions on documentation style. I will try to demonstrate my suggestions by writing a document that justifies them. I'm an advocate of learning by example. As Mark Twain said, "Few things are harder to put up with than the annoyance of a good example" (Samuel Langhornne Clemens (1835-1910)).

Pulling content from CVS

A large part of the WebWork 2.2 documentation effort is to make documentation easier to handle in the future. At on the onset of this effort, everyone agreed that pulling as much source code, examples, and documentation from source control would help greatly. As such, we've installed a modified version of the snippet macro in the OpenSymphony wiki.

The standard way to use it is to do the following:

{snippet:id=description|javadoc=true|url=com.opensymphony.xwork.interceptor.LoggingInterceptor}

or

{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork.interceptor.LoggingInterceptor}

or

{snippet:id=sitegraph-usage|lang=none|url=webwork/src/java/com/opensymphony/webwork/sitegraph/sitegraph-usage.txt}

or

{snippet:id=ajax-validation-example|lang=xml|url=webwork/webapps/ajax/src/webapp/lesson1/example.jsp}

Where:

• id is the name of the snippet (*required).
• url is the URL where the snippet can be found (required).
• lang is the language that the code block should be required as. If this snippet is simply text, don't include this parameter and the content will be printed outside of a code block.
• javadoc indicates if the content is within a JavaDoc block. If this is set to true, then the preceeding "* " (asterisk-space) characters will be stripped before printing the content out. Also, the content is assumed to the HTML escaped already and therefore won't be escaped again.

All snippets are marked off by the pattern START SNIPPET: XXX and END SNIPPET: XXX where XXX is the name of the snippet that is assigned in the id attribute of the macro. The URL is typically a location that points to the project's source control contents.

A note about URLs

As you probably noticed in the examples, there are several formats that the URL patterns can be in. A fully-qualified URL is always allowed, though that is often not practical. We've customized the macro to be a bit more intelligent with the URL attribute:

• If the URL appears to be a class, we assume it lives in src/java, convert all the dots to slashes, and then append .java to it.
• If the URL doesn't start with "http", then it is assumed to start with _https://opensymphony.dev.java.net/source/browse/*checkout*/_^{Image Removed}, as you saw in the third example.

Note that the short-hand class notation will only work for top-level projects (WebWork, OSWorkflow, etc) and not any sub-projects within the projects, such as example webapps in WebWork. If you wish to include content from a class in a sub-project, you'll need to list out the full path, like in the fourth example.

A note about snippet markers

All snippet markers should be commented out if possible. How they are commented out depends on where the snippet is. If the snippet is for HTML or XML, you can do:

<!-- START SNIPPET: xxx -->
...
<!-- END SNIPPET: xxx -->

If the snippet is in Java code, you can do:

if (true != false) {
    // START SNIPPET: xxx
    System.out.println("This is some silly code!");
    // END SNIPPET: xxx
}

If the snippet is found in JavaDocs, you should use HTML comments as they won't render in the JavaDocs. For XML examples in JavaDocs (see Timer Interceptor for an example), it can be a bit tricky. This is because in your JavaDocs you want to use the <pre> tag, but you don't want the wiki to display it. A good technique is to embed the snippet markers inside the <pre> tag:

 * <pre>
 * <!-- START SNIPPET: example -->
 * &lt;!-- records only the action's execution time --&gt;
 * &lt;action name="someAction" class="com.examples.SomeAction"&gt;
 *     &lt;interceptor-ref name="completeStack"/&gt;
 *     &lt;interceptor-ref name="timer"/&gt;
 *     &lt;result name="success"&gt;good_result.ftl&lt;/result&gt;
 * &lt;/action&gt;
 * <!-- END SNIPPET: example -->

About Headings

This section refers to: Notation Guide >> Headings.

Headings should definetly be used. This sections tries to justify why.

First rule: don't use "h1" at the top of each page. The page title serves as the "top level header" already, so there is no need to duplicate that information again. Also, when the docs end up the website, SiteMesh will place a top level "h1" element using the page title.

Document sections

Headings can help you divide your document in sections, subsections, sub-subsections and so forth.

Advantages

Your document becomes more organized.

Disadvantages

If you exaggerate you could fragment your text too much.

Headings capitalization

I think headers h1 and h2 should have all words capitalized (such as "Vitor's Suggestions on Documentation Style" and "About Headings"), but h3 and smaller would have just the first word (such as "Headings capitalization"). Except, of course, for words that are always capitalized (eg. "Understanding WebWork's importance to OpenSymphony and its community"). This gives even more importance to bigger headings.

Avoid skipping headers

I mean, avoid going from a h1 directly to a h3 without using h2 before. This would be like havin a section 1.1.1 directly below section 1, without the existance of section 1.1.

More on Text Effects

This section refers to: Notation Guide >> Text Effects.

Text effects should be largely used, although I have some questions on some of them. Strong, emphasis, and inserted can be used to denote importante parts of a sentence. But I really think inserted should have been called underline in the notation guide. I don't see the point of using deleted, since when someone changes a page and deletes stuff, Confluence keeps the old versions in history.

I can't think of a situation in WebWork's doc for ^superscript and _subscript, but it doesn't hurt to mention them. I can't say anything about %span% because I frankly don't know what it does. Monospaced is heavily used, for instance, to refer to webwork-default.xml file or items in source code examples: <xmltag />, JavaClass or javaVariable.

Colors should be used in very specific cases, or else each documentation writers would color his/her pages the way he/she thinks it's better, and it would look like a mess. One such specific case in which colors can help is when you want them to work as tags or captions. For (a lame) example, in this paragraph, guidelines are in red and justifications are in blue. Yes, it's a really really lame example, I know.

Text Breaks

This section refers to: Notation Guide >> Text Breaks.

Text breaks shouldn't be used. If you'd like paragraphs or headings to have more spacing (before or after), the style sheet should be changed, not the contents. Patrick explained this a long time ago. Other stuff in this section (paragraphs, horizontal ruler, — symbol and – symbol) can be used when necessary.

Links

This section refers to: Notation Guide >> Links.

All types of links can and should be used. I already used a few in this document. Just watch out for links to non-existing pages when writing on the official documentation.

Lists

This section refers to: Notation Guide >> Lists.

Lists can be used for many purposes. Every time we list some things that are in order, ordered lists are used. If they don't have a specific order, unordered lists are the case. List should be nested if needed for a better organization. Unordered lists should be created only with the * (star) notation only, so all pages use the same style of bullet.

• This is an unordered list in star notation;
• Items can have sub-items
  • That can have sub-items
    • That can have sub-items...
      • What is the limit?
• Mixing ordered and unordered lists is possible:
  1. One;
  2. Two;
  3. Three.

Images and Icons

This section refers to: Notation Guide >> Images and Notation Guide >> Misc.

External images should be used only when strictly necessary (meaning, don't use images as list bullets or box icons). Also, try to use only images that are very unlikely to be removed from its current URL, to reduce document maintenance. Pay attention on copyright issues too! Attached images are less prone to become missing links, however, we should not clutter the documentation with unnecessary attachments and copyrights are also a issue here.

Example: Image Removed

Icons are cool in a number of situations. Some of them, such as , , or can make the documentation look professional, but some others, such as and may give a feeling of amateurship and I wouldn't advise them for pages that are exported to form the official documentation.

Tables

This section refers to: Notation Guide >> Tables.

Tables are very useful when lists just don't do it. Meaning: don't write a table when a list suffices. Tables are more organized, because you can align the text in columns. Since the markup text for tables in confluence is not very easy to read, remember complex and big tables are very hard to maintain.

The table below was copied from a reference page on WebWork's configuration (just the first two lines were copied). This is an example where tables are good: a list wouldn't be as organized as this table to display these files and their properties.

Advanced Formatting

This section refers to: Notation Guide >> Advanced Formatting.

I've already made my point about info, warning, tip and note boxes. Other interesting markups are noformat and code. The former can be used for general purpose text while the latter is used to display example source code, be it HTML, XML, Java or anything that is part of a software solution. When displaying something that has a name, use a title, as the example below demonstrates.

/** Hello World class. */
public class HelloWorld {
  /** Main method. */
  public static void main(String[] args) {
    System.out.println("Hello, World!");
  }
}

A typical example of noformat would be the command line statements to compile and run the code above. We should also standardize terminal notation ({$} for command prompt).

$ javac HelloWorld.java

$ java HelloWorld
Hello, World!

Do not use tabs inside noformat and code, use two spaces instead. This way your code is indented but keeps lines short. Large lines should be splitted as to fit in a 800x600 resolution screen without horizontal scroll bars.

Your Comments Please

...