Page History

...

First, we want the documentation to be as both complete as possibleand concise. 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 practical introduction to the framework, so newcomers can get started as easily as possible. SecondTo 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 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 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. Instead of "See Documentation Style Guide page", try For example: "See Documentation Style Guide."

...

• Use "the framework" or "Struts 2" to refer to Struts 2 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.

...

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

The root of the documentation is the "Home" page, which is also the "Welcome" page. The documnentation 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.

...

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

Please add new shortcuts as needed.

About Headings

This section refers to: Notation Guide >> Headings.

About h1

About Headings

This section refers to: Notation Guide >> Headings.

About h1

Don'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.

...

Your document becomes more organized.

Disadvantages

If you exaggerate you could fragment your text too muchToo many headings can fragment the text.

Headings capitalization

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

...

The headers form an outline for the page. It When writing term papers, it is not a good practice to skip outline levels. When writing hypertext, and 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.

...

Text Breaks

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

Text breaks should not be used to format blocks ont he 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.

...

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

Example: Image Removed Image Added

Icons

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

...

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 Confluence is not very easy to read, remember complex and big tables are very 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.

...

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.

...

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 redundancy (without sacrificing ease of use).

...

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 any file for reuse. The macro fetches those snippets from the a repository and merges the conntent content into the documentation.

Here are some examples of the snippet macro in action:

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

or

Example snippet usage

{snippet:id=example|

...

lang=xml|

...

javadoc=true|url=struts2/core/src/main/java/org/apache/struts2/components/If.java}

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}

...

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.

...

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.

...

If the snippet is embedded in Javadocs, within Javadoc comments use HTML comments to declare the snippet 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..

When using the <pre> tag within Javadoc comments One 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 -->

...

* </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