{widget:url=http://au.youtube.com/watch?v=-dnL00TdmLY}
Infinispan uses this Confluence instance to store documentation and FAQs. The documentation is organised into:
|
|
|
Future plans |
|
Tutorials for using Infinispan |
This will be developed into a Getting Started Guide, where each tutorial as an associated quickstart example |
|
|
Goes into depth on using and configuring Infinispan |
This will be split into a Developer Reference Guide, a Configuration Guide and a Tuning Guide |
|
|
An explanation of the terminology used by Infinispan |
|
|
|
Contains both product and technical FAQs |
Each Q&A will be moved into a document and included into the outline document |
Editing and adding pages on Confluence is restricted to regular contributors to Infinispan (if you think you should have access, or want to become a regular contributor to the documentation, then please email infinispan-dev@lists.jboss.org.
Infinispan has both this Confluence instance, and the SBS instance at http://community.jboss.org/wiki/Infinispan. Documentation and FAQs belong in Confluence, whilst design notes, meeting notes and user contributed articles belong on SBS.
Once the final set of guides (as described in the table above) is complete, there will be additional guidance here to describe how to decide which guide to place content in.
You should always use wiki markup, it gives you much greater control over output format. The "Full notation guide" link in the "Help Tips" panel to the right (on the edit page) gives a full list of markup available.
This section discusses the typical markup you would use to write a documentation chapter. The Style and Grammar guide will discuss the writing style you should use.
Let's start at the beginning - headers, page structure, and the table of contents.
This Confluence instance is styled to produce structured documentation. Each node in the Infinispan space can have children, producing a tree of nodes. Note that pages are actually stored in a flat structure in the Infinispan space, they are just logically arranged into the tree. This means that URLs do not reflect the tree structure, and names of documents must be unique within the space.
The child nodes of the Infinispan space represent the various guides, and the FAQs. The child nodes of each guide represent the sections of the guides. Some sections of a guide may be further split into subsections stored in different pages (it is likely this was done because a section was getting large).
The include macro is used to display inline the contents of the various sub pages into the top level guide page, and if a section is made up of child pages, each child page should be inlined into the section page using the include macro.
The include macro is not automatically updated if you change a page name!
Confluence auto-generates the table of contents (using the toc macro) for the various guides, based on the headings used in the guide. As the include macro does not print the title of the page you are including, it is necessary to add the title above the include macro. You should not use the toc macro except on the main guide page.
h1 headers should only be used to name sections of guide, h2 headers to name sub-sections and so on. You should not skip header levels. Headings should follow the same capitalization rules as a sentence - only capitalize the first letter and proper nouns.
For an example, take a look at the wiki markup for the Contributing to Infinispan guide.
You will likely want to introduce some inline formatting for text. Here are the various styles you should use.
|
Style |
Use |
|
bold |
Bold should be used for emphasis only. You should never use another style to give emphasis. |
|
italic |
Italic should be used when you introduce a new piece of terminology. For example "Infinispan is a data grid". Further uses of the term do not need to be italicised. |
|
underline |
Underline should not be used |
|
strikethrough |
Strikethrough should not be used |
|
fixed width font |
A fixed width font should be used whenever you refer to a class, variable, method by name, whenever you make a reference to a path on filesystem, or whenever you refer to a command the user can execute. A fixed width font should be used when referring to a sequence of clicks required by a user in a GUI. the -> symbols should be used to indicate the transition through a nested menu. |
|
code block |
Should be used whenever you have a multi-line code example, or are expressing an instruction for a user to do something |
|
quotation |
Should be used whenever you refer to text someone, or something, else has written, for example the "Help Tips" on the right hand side of the edit page. You may wish to quote a statement to indicate that your text is not overly precise. Quotes should not be used to refer to a variable, class or method name, or a filesystem path or command |
|
blockquote |
Should be used for multiline quotes |
|
Color |
Colored text should not be used |
You will normally wish to use an unordered list, however a numbered list is useful when expressing a set of steps the user should take. There are no "definition list" macros available in Confluence, so a table makes a good alternative.
You can make nested lists by using "double" markup.
The trailing sentence in a list or a table should normally not have a full stop at the end.
Often, you will want to introduce a list or a table using a sentence. If you do this, a colon is often used to punctuate the end of the sentence, rather than a full stop/period.
Links should be used as normal!
Confluence supports three admonition styles, and you are encouraged to use them in your documentation as they allow the flow of information to the reader to be controlled, by moving orthogonal information out of the main body of text.
|
tip |
A tip should be used when you want to convey useful information to the user. If the user does not read the tip, it will have no impact on them understanding your documentation, however they will gain useful extra information by reading the tip |
|
note |
A note should be used when you wish to convey extra information to the user. Without the information the user may struggle to completely understand your documentation |
|
warning |
A warning should be used when the there is some counter-intuitive information to be called out to the user. For example, that the following information is out of date. |
You can use the title attribute to give the admonition a title
If you are describing the use of a GUI, or showing results of some operation, images embedded in the page can bring the documentation to life for the reader. Images can be attached to the page using the Tools menu, and then linked. The "Full notation guide" discusses the syntax for embedding images. If you are embedding the image to describe a series of steps taken in a GUI, it is not necessary to title your image, otherwise you should give every image a title.
Giffy is supported in this Confluence instance, allowing you to easily create drawings online. For more, read the Giffy documentation for more information.
Confluence supports a charting macro, however it is recommended that you embed charts as images, generating the chart using your favourite program.
The use of the panel macro is not recommended.
Confluence allows you to natively embed video, however the use of this is not recommended, instead it is recommended the widget macro is used to connect to Vimeo or YouTube. The Screencasts section describes the creation of screencasts and upload of video to Vimeo or YouTube. To embed a video using the widget macro simply reference the URL to the video, for example:
{widget:url=http://au.youtube.com/watch?v=-dnL00TdmLY}
This produces
You can also embed Google Docs documents, Twitter searches, slide decks from SlideShare, and presentations from SlideRocket. Just follow the above example, substituting the URL for your media.
Confluence includes a code macro, but unfortunately it is not very advanced. This Confluence instance also supports the snippet macro which can be used to include text from other sites. The use of the snippet macro is strongly recommended as it ensures that code samples do not get out of date. It is critical that you add a title to the your snippet, and it is also recommended you enable linenumbers and trim the text. For example
{snippet:title=My Code Sample|language=none|linenumbers=true|first=2|last=5|url=github.com/infinispan/infinispan/raw/master/README.mkdn}
Which results in:Code Snippet error: Unable to retrieve the URL: https://github.com/infinispan/infinispan/raw/master/README.mkdn status code: 404.
The snippet macro doesn't like the default "raw" link that GitHub provides. Instead, craft a URL like github.com/infinispan/infinispan/raw/master/README.mkdn; to do this, take the URL from your browser, and insert raw/master after the project name and before the path to the file.
If you want to indicate that the user needs to substitute a variable in a code sample with their own, then use < and > around the variable name. For example, to indicate the user needs to checkout a topic branch from git:
git checkout -b <topic>
By using a consistent voice throughout the documentation, the Infinispan documentation appears more professional. The aim is to make it feel to the user like the documentation was written by a single person. This can only be completely achieved by regular editing, however in order to make the workload of the editor lighter, following these rules will produce a pretty consistent voice.
Never use abbreviations. On the other hand, contractions are fine.
Always use the project name "Infinispan". Never abbreviate it.
Always write in the second or third person, never the first (plural or singular forms). Use the second person to emphasize you are giving instructions to the user.
Naturally, most people write in the first person, and, typically find it the easiest form to write, however without a lot of care it can produce the most "unprofessional" text. Conversely, writing in the third person is trickier, but will produce text that feels well written almost without fail. The first person can be used for emphasis but in general it is recommended to avoid it unless you feel confident!
Writing entirely in the third person can produce quite "dry" text, so it is recommended that you use the second person when you are giving instructions to the user. This could be when you are walking through a sequence of steps they should perform, or could be when you are stating that they must do something in order for them to succeed.
So, are there any tricks to reformulate a sentence so the first person is not used?
Use the passive voice "I recommend" can become "It is recommended". However, extensive use of the can produce boring, dry and indefinite text, so don't do this too much!
Change the subject. For example you can change "Here we discuss" to "This section discusses"
Use a "chatty" style. Although the use of the first person is avoided, the documentation shouldn't be too dry. Use the second person as needed. Short sentences and good use of punctuation help too!
If you define a list, keep the ordering of the list the same whenever you express the list. For example, if you say "In this section you will learn about interceptors, commands and factories" do not go on to say "First, let's discuss factories". This will subconsciously confuse the user
You should only capitalize proper nouns only. For example "data grid" is lower case (it's a concept), whilst "Infinispan" is capitalized (it's a project/product name)
You should always use American spelling. Enable a spell checker!
Use the definite article when discussing a specific instance or the indefinite article when describing a generalization of something; generally you omit the article when using a name for a project or product.
Infinispan uses a logging framework to communicate messages to the user, the logging framework used by Infinispan is JBoss Logging.
Let's dig into this. First, the sentence states that "Infinispan uses logging", and the indefinite article is used - we are not stating which of many possibilities is used. Second, the sentence goes on to discuss the logging framework Infinispan uses, and here the definite article is used, as the specific framework in use is discussed. Finally, the sentence is concluded by stating that the logging framework used is called "JBoss Logging", and as this is a product name, no article is used.
This is not a formal or complete description, but is a good rule of thumb.
Keep the tense the same. It's very easy to slip between the present, past and future tenses, but this produces text that is feels "unnatural" to the reader. Here's an example:
Data is collected from Infinispan every hour. Upon analysis the data showed that Infinispan is 2 million times faster than it's nearest competitor
You may not have noticed, but the phrase starts using the present tense (is) and slips into the past tense (showed). This is clearly not actually the order in which the events happened!
Of course, if you are actually describing the progression of time, then changing tenses is fine. For example:
In the last section you were shown how to configure Infinispan using XML, and in the next section you will be shown how to configure Infinispan programmatically.
If you are telling the user about a procedure they can follow, do be explicit about this, and enumerate the steps clearly
When writing a glossary entry, you should follow the Basically Available, Soft-state, Eventually-consistent (BASE) as a template.
If the entry is commonly referred to using an acronym, then the title should consistent of the fully expanded name, with the acronym in brackets. You can then use the acronym always within the main text body
If you want to refer to other glossary articles using links in the text body, then just link them with no alternative text
If you want to make external links (e.g. wikipedia, user guide), then add a h2 header "More resources", and list them there. This clearly indicates to users when they are moving outside of our definitions
TODO