You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 25 Next »

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 as complete as possible. This is job one! The documentation should be a repository of all the tips and tricks we use in our own applications, and it should also be a quick but comprehensive introduction to the framework, so newcomers can get started as easily as possible.

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 lot of 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

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

Also excellent, but more expensive:

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. Instead of "See Documentation Style Guide page", try "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, and, of course, we're now calling the framework "Action" too!

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

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

About Headings

(info) 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

If you exaggerate you could fragment your text too much.

Here we go again!

This segment an example of overusing headings. This whole "Headings" section has so few paragraphs that it really should have been written in just one section. The "advantages" and "disadvantages" would be just as easy to render as a table.

Headings capitalization

Try to use intial 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 capilazation sytles, we emphasize the importance of bigger headings.

Avoid skipping headers

The headers form an outline for the page. It is not good practice to skip outline levels, and it is not a good practice to skip heading levels either. Try not to skip from a h2 to a h4.

Too many headings?

If you find yourself writting too many h2 headings in a single page, consider breaking the page into child pages.

More on Text Effects

(star) 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 action.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

(star) This section refers to: Notation Guide >> Text Breaks.

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

Lists

(star) 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

(star) 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 inclued 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 orginal or public domain work, or the author has donated the image to the foundation.

Example:

Icons

Use (info), (question), (warning), and (tick) to bullet important one-liners. Use (lightbulb) 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 (smile) and (thumbs up) should be used with care or avoided.

Tables

(star) 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 very easy to read, remember complex and big tables are very hard to maintain.

File

Optional

Location (relative to webapp)

Purpose

web.xml

no

/WEB-INF/

Web deployment descriptor to include all necessary WebWork components

struts.xml

no

/WEB-INF/classes/

Main configuration, contains result/view types, action mappings, interceptors, and so forth

Advanced Formatting

(star) 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.

Try to specify the language for {code} blocks.

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

(warning) 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.

Compiling and Running Hello World
$ 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 redudency (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 the Javadocs and source code for reuse. The macro fetches those snippets from the repository and merges the conntent into the documentation.

Use the Source!

Before writing any new content, ask yourself if we could place the content in the repository in either one of the example applications or the Javadocs. Rather than contrive an example, can you pull a snippet from one of the applications? Rather than reiterate Javadoc, could we update the Javadoc and make it a snippet?

Here are some examples of the snippet macro in action:

{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}

Legend:

id

The name of the snippet (required).

url

The URL where the snippet can be found (required).

lang

The language that the code block. If this snippet is simply text, don't include this parameter and the content will be printed outside of a code block.

javadoc

If true, the content is within a Javadoc block. If this is set to true, then the preceeding "* " (asterisk-space) characters will be stripped before merging the content. Also, the content is assumed to be already HTML escaped and 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.

About URLs

As you probably noticed in the examples, there are several formats for URL patterns. 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.

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.

Commenting HTML or XML snippets
<!-- START SNIPPET: xxx -->
...
<!-- END SNIPPET: xxx -->
Commenting snippets in Java code
if (true != false) {
    // START SNIPPET: xxx
    System.out.println("This is some silly code!");
    // END SNIPPET: xxx
}

If the snippet is embedded in Javadocs, use HTML comments as they won't render in the Javadocs. For XML examples in Javadocs can be tricky. (See Timer Interceptor for an example.). Javadocs want to use the <pre> tag, but you don't want that tag in the snipped content.

One technique is to embed the snippet markers inside the <pre> tag.

Snipping XML examples from Javadoc content
* <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 -->

Next: Meeting Minutes

  • No labels