Documentation Style Guide

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

...

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.

...

  • 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

...

Shortcut

Purpose

Usage

Result

primer

A bookmark in our Key Technologies Primer

[javabeans@primer]

javabeans@primer

s2jirajira

A ticket in our issue tracker

[WW-2111@s2jira2111@jira]

WW-2111@s2jira2111@jira

s2plugins

S2 Plugin Repository

[tiles-plugin.html@s2plugins]

tiles-plugin.html@s2plugins

s2site

The Struts 2 website

[docs/home.html@s2site]

docs/home.html@s2site

...

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

(tick) Try to use snippets for code blocks whenever possible!

...

A URL must start with a valid prefix. Currently there There are two valid prefixes that are useful for Struts documentation purposes.types of prefixes:

  • com.opensymphony.xwork2. (notice the period) 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 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:

...

To include a snippet from httphttps://svn.opensymphonyapache.comorg/svnrepos/xworkasf/struts/struts2/trunk/xwork-core/src/main/java/com/opensymphony/xwork2/validator/validators/StringLengthFieldValidator.java the two possible methods are:

Code Block
{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.

...

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