THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
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 documenation 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 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 "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.
...
Your document becomes more organized.
Disadvantages
If you exaggerate you could fragment your text too muchToo many headings can fragment the text.
| 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. |
...
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.
...
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.
...
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.
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 |
...
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.
...
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 content into the documentation.
| Tip | ||
|---|---|---|
| ||
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? |
...
- Javadoc
- {snippet:id=
...
- javadoc|javadoc=true|url=
...
- org.
...
- apache.
...
- struts2.
...
- components.
...
- If}
...
- Tag Attributes
- {snippet:id=
...
- tagattributes|javadoc=
...
- false|url=struts2/docs/tags/If.html}
or
{snippet:id=sitegraph-usage|lang=none|url=webwork/src/java/com/opensymphony/webwork/sitegraph/sitegraph-usage.txt}
...
- Coding Examples
- {snippet:id=
...
- example|lang=xml|javadoc=true|url=
...
- struts2/core/src/main/java/org/apache/struts2/components/If.java}
| Snippet Attributes |
|---|
...
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.
...