...
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.
...
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
...
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
...
- 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
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.
...
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.
Warning | ||
---|---|---|
| ||
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.
...
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
.
Tip | ||
---|---|---|
| ||
If you find yourself writting too many |
More on Text Effects
This section refers to: Notation Guide >> Text Effects.
...
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 ont he 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.
...
- 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?
- That can have sub-items...
- That can have sub-items
- Mixing ordered and unordered lists is possible:
- One;
- Two;
- Three.
Images
This section refers to: Notation Guide >> Images and Notation Guide >> Misc.
...
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 ,
,
, and
to bullet important one-liners. Use
to highlight cross references.
...
Casual icons like and
should be used with care or avoided.
Tables
This section refers to: Notation Guide >> Tables.
...
File | Optional | Location (relative to webapp) | Purpose |
---|---|---|---|
no | /WEB-INF/ | Web deployment descriptor to include all necessary WebWork components | |
no | /WEB-INF/classes/ | Main configuration, contains result/view types, action mappings, interceptors, and so forth |
Advanced Formatting
This section refers to: Notation Guide >> Advanced Formatting.
...
Code Block | ||
---|---|---|
| ||
$ 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.
...
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.
- 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*/_, as you saw in the third example.
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.
...
Code Block | ||||
---|---|---|---|---|
| ||||
* <pre> * <!-- START SNIPPET: example --> * <!-- records only the action's execution time --> * <action name="someAction" class="com.examples.SomeAction"> * <interceptor-ref name="completeStack"/> * <interceptor-ref name="timer"/> * <result name="success">good_result.ftl</result> * </action> * <!-- END SNIPPET: example --> |