You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Vitor's 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)), so this paragraph already tried to demonstrate some text effects that can be used (more on this later).

About Headings

(star) 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.

Handy Hint

One thing that I like to do is leave five blank lines before h1 headings, three before h2's and two before h3's. Also, in Portuguese (I'm Brazilian), we write small numbers using their names instead of numeric representation (five instead of 5). I don't know if this is also a good practice in written english.

Aren't tip boxes neat?

Be Careful

If you find yourself writting too many h1 headings in a single page, consider breaking the page into child pages and linking to them.

Aren't note boxes neat?

More on Text Effects

(star) This section refers to: Notation Guide >> Text Effects.

Text effects should be largely used, although I have some questions on some of them. Strong, emphasis, and inserted can be used to denote importante parts of a sentence. But I really think inserted should have been called underline in the notation guide. I don't see the point of using deleted, since when someone changes a page and deletes stuff, Confluence keeps the old versions in history.

Superscript can be used for math equations (eg. x^2^+2x+4) and subscript for chemistry formulas (eg. H~2~O). But I can't think of a situation this would be needed in WebWork's doc. I can't say anything about %span% because I frankly don't know what it does. Monospaced is heavily used, for example, to refer to webwork-default.xml file or to reference items in source code examples, for instance: <xmltag />, JavaClass or javaVariable.

Boxes vs. Block Quotes

I think boxes and block quotes do the same job, but boxes are better. Therefore, I suggest we don't use block quotes.

Aren't info boxes neat? Aren't them all neat? By now you may have realized I think we should definetly use them...

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.

Text Breaks

(star) 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.

(star) This section refers to: Notation Guide >> Links.

All types of links can and should be used. I already used a few in this document.

Lists

(star) This section refers to: Notation Guide >> Lists.

Lists can be used for many purposes. Every time we list some things that are in order, ordered lists are used. If they're not in order, unordered lists are the case. List should be nested if needed for a better organization. Unordered lists should be created only with the * (star) notation, so all pages use the same style of bullet.

  • 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?
  • Mixing ordered and unordered lists is possible:
    1. One;
    2. Two;
    3. Three.

List indentation

Use tabs to indent nested lists. This way your page's markup is more readable and easier to maintain.

Images and Icons

(star) This section refers to: Notation Guide >> Images and Notation Guide >> Misc.

External images should be used only when strictly necessary (meaning, don't use images as list bullets or box icons). Also, try to use only images that are very unlikely to be removed from its current URL, to reduce document maintenance. Pay attention on copyright issues too!

Example:

Attached images are less prone to become missing links. However, we should not clutter the documentation with unnecessary attachments and copyrights are also a issue here.

Tables

(star) This section refers to: Notation Guide >> Tables.

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 is not very much readable, remember complex and big tables are very hard to maintain.

The table below was copied from a reference page on WebWork's configuration. Just the first two lines were copied. This is an example where tables are good: a list wouldn't be as organized as this table to display these files and their properties.

File

Optional

Location (relative to webapp)

Purpose

web.xml

no

/WEB-INF/

Web deployment descriptor to include all necessary WebWork components

xwork.xml

no

/WEB-INF/classes/

Main configuration, contains result/view types, action mappings, interceptors, etc

Advanced Formatting

(star) This section refers to: Notation Guide >> Advanced Formatting.

I've already made my point about info, warning, tip and note boxes. Other interesting markups are noformat and code. The former can be used for general purpose text while the latter is used to display example source code, be it HTML, XML, Java or anything that is part of a software solution. When displaying something that has a name, use a title, as the example below demonstrates.

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

Do not use tabs inside noformat and code. Use two spaces. This way your code is indented but does not make the user scroll horizontally to read it. For this same reason, try to break big lines 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 wronte something wrong or if this proposed Style Guide is missing something.

  • No labels