THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Suggestions on Documentation Style
This page contains my suggestions on documentation style. I will try to demonstrate my suggestions by writing a document that justifies them. I'm an advocate of learning by example. As Mark Twain said, "Few things are harder to put up with than the annoyance of a good example" (Samuel Langhornne Clemens (1835-1910)).
About Headings
This section refers to: Notation Guide >> Headings.
Headings should definetly used. This sections tries to justify why.
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 is definetly an example of this, since this whole "Headings" section has such few paragraphs that it really should have been written in just one section. Aren't warning boxes neat? |
Headings capitalization
I think headers h1 and h2 should have all words capitalized (such as "Vitor's Suggestions on Documentation Style" and "About Headings"), but h3 and smaller would have just the first word (such as "Headings capitalization"). Except, of course, for words that are always capitalized (eg. "Understanding WebWork's importance to OpenSymphony and its community"). This gives even more importance to bigger headings.
Avoid skipping headers
I mean, avoid going from a h1 directly to a h3 without using h2 before. This would be like havin a section 1.1.1 directly below section 1, without the existance of section 1.1.
...
| Note | ||
|---|---|---|
| ||
If you find yourself writting too many Aren't note boxes neat? |
More on Text Effects
This section refers to: Notation Guide >> Text Effects.
...
Colors should be used in very specific cases, or else each documentation writers would color his/her pages the way he/she thinks it's better, and it would look like a mess. One such specific case in which colors can help is when you want them to work as tags or captions. For (a lame) example, in this paragraph, guidelines are in red and justifications are in blue. Yes, it's a really really lame example, I know. 
Text Breaks
This section refers to: Notation Guide >> Text Breaks.
Text breaks shouldn't be used. If you'd like paragraphs or headings to have more spacing (before or after), the style sheet should be changed, not the contents. Patrick explained this a long time ago. Other stuff in this section (paragraphs, horizontal ruler, — symbol and – symbol) can be used when necessary.
Links
This section refers to: Notation Guide >> Links.
All types of links can and should be used. I already used a few in this document. Just watch out for links to non-existing pages when writing on the official documentation.
Lists
This section refers to: Notation Guide >> Lists.
...
| Tip | ||
|---|---|---|
| ||
Use tabs to indent nested lists. This way your page's markup is more readable and easier to maintain. |
Images and Icons
This section refers to: Notation Guide >> Images and Notation Guide >> Misc.
...
Icons are cool in a number of situations. Some of them, such as 
, 
, 
or can make the documentation look professional, but some others, such as and 
may give a feeling of amateurship and I wouldn't advise them for pages that are exported to form the official documentation.
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, etc |
Advanced Formatting
This section refers to: Notation Guide >> Advanced Formatting.
...
Do not use tabs inside noformat and code, use two spaces instead. This way your code is indented but keeps lines short. Large lines should be splitted as to fit in a 800x600 resolution screen without horizontal scroll bars.
Your Comments Please
Please contribute to this page. Let me know if you have a different opinion on something (please justify it). Please warn me if I wrote something wrong or if this proposed Style Guide is missing something. Feel free to correct my english, since I'm not a native speaker.