Article Guidelines

Article Guidelines

1 Objective

You will learn how to create and improve wiki articles. You will also find a number of hints.

2 Requirements

Willing to write good articles. For better understanding of the formatting details you should open the XWiki Syntax in a different tab. Be aware, as this article is a little bit special, it does not comply all the rules, that are mentioned here.

3 Essentials

3.1 Screen Shots

Use screen shots that contain meaningful examples (not just empty screen shots) Think about to open one of the menus that gives the reader a hint how to get there.

You can also work on your screen shot:

• Create pointers/arrows/circles that emphasize the most important details of your screen shot.
• Add some numbers on your screen shot that you explain.

3.2 Article Types

There are three main types of articles:

• End User articles
• Configuration articles
• Development articles

3.3 Structure

First structure your page. Write a page title and all chapter and subchapter titles. The general structure for larger article is:

1. Objective: What is this article about?
2. Requirements: What should the reader have installed? What should he or she already know? Provide links to articles with more basic content.
3. Overview chapter
4. Basic concept chapter A
5. Basic concept chapter B
6. Advanced concept chapter A
7. Advanced concept chapter B
8. Further Reading: Where should or can the reader continue his studies? These links can also point outside the wiki.

Titles
Use an self-explanatory titles. The noun of the title should be in Capital Letters, ex: "Configuration+in+Detail". Reuse the same title for the URL and the document text title that later appears in the breadcrumbs. Avoid articles "the", "a" in titles and heading, be brief, don't write "About the Service Configuration" but "Service Configuration", not "Understanding Portal Gadgets" but "Portal Gadgets". A capital letter is used for the first word and for every significant word. A little word like the, of, and or in is not capitalized unless it is the first word.

3.4 Version information

If your text is about a specific version of a product add an additional info box at topmost position (above the title) of your article:

3.5 Terms

Define the terms (navigation bar, user workspace) when you first mention them (or at the beginning of the document or chapter). After that use consistently only these terms. For example, do not define a "main node" and continue later using the term "principal node" if both are the same.

3.6 Write for the Reader

The target reader is the most important person. Always imagine a reader that doesn't know anything. Imagine all the questions that he or she might have and answer them in your text. Don't be too ashamed to explain things everybody should know - just explain it, it only costs you a few lines. The reader is not your colleague that worked with the product for 5 years. Your reader can be an eXo beginner that only has used PHP or C#. As a good writer you explain all possibly new terms and concepts and you add useful links for further study.

3.7 Activate

Talk to the reader, use "you" and "your", "you will see", etc. Be positive us expressions like "let's see/find out/look for". That is less abstract and more motivating. In a tutorial article that can also be a little bit funny "your boss asks for", "your class has got a problem".

Also avoid also passive construction, always mention the actor. Compare:

• "The testFunction is called during execution."
• "The container calls your calculatePrice() method right after startup."
• "The service must be started before being used in the application."
• "You must first start the service before you can call it."

3.8 Examples

Use meaningful examples instead of abstract descriptions. A precise example is easier to understand than theoretical definitions. Sometimes you need more words - but that doesn't matter. Compare:

• "A service is a java class."
• "Let's look at this code example: ...[code]… You see that your service is just a normal java class."

3.9 Keep it simple

A technical wiki is not a novel. You may repeat keywords as often you consider it to be necessary. Using expressions like "this, it, the latter, the former, the one" only create confusion. Start a new sentence for each new concept, idea or detail. Compare:

• "The RootContainer, PortalContainer, StandaloneContainer all inherit from PicoContainer; the latter being also used for test purposes can provide the same functionality as the second one."
• "There are three container types: RootContainer, PortalContainer, StandaloneContainer. They all inherit from PicoContainer. You use either the StandaloneContainer or the PortalContainer because they both provide the same functionality. The StandaloneContainer is also used for test purposes." (Better even though longer)

3.10 Repeat

Repeat important facts. That might seem needless. But there is always a reader who didn't notice the definition you mentioned along the way - he or she will be thankful. You can write:

• "You still remember..."
• "As you have learned..."
• "As you have seen..."
• "Now you understand..."
• "Be aware of the fact/definition ..."
• "Don' forget that..."

• "As mentioned before ..."
• "As defined/specified above..."

3.11 Reason

Always mention the reason why something has to be done using the way you indicate. That can be a reference to the architecture ("The container will call a constructor of your service so that you should provide at least the default constructor.") or an indication ("You must first define your Drive because the File Explorer needs it."). Use "because", "therefore", "for this reason", "that's why", "in order that", "so that", "for this purpose".

4 Format Issues

4.1 Table of contents

Repeat the title of your article right at the beginning. Surround it with <h1>. This way the title is rendered as a heading but is not part of the table of contents.

Structure your page with chapter titles, put a "1 " in front of the main chapter titles and a "1.1 " for the sub chapter titles. By doing this the table of contents is properly rendered.

If your article is longer than two screens, put a table of content at the beginning of your article. Use the toc macro:

#toc("1" "3" "true")

4.2 Indentation

• Use two backslashes "\\" to continue the text in the next line respecting the indentation.
  
  That allows to write longer texts and even paragraphs that stay
  at the right inside
  using the indentation of the list.
• That gives your page a better structure.

4.3 Code Examples

Code examples are good and help the reader understand what you mean. Use them. Sourround XML snippets with the code:xml macro:

<xml-snippet>content in narrow box, but you can use any [] #info() etc. inside it</xml-snippet>

In other cases you can use {code:none}. Do not use {code} (which defaults to "java") or *{code:java}, the results are not good. The code macro has the problem, that it renders a quite narrow box, therefore better surround your code with <pre>text/</pre>, if there are no conflicts with the xwiki syntax inside your code example.

larger box

4.4 Info Boxes

4.5 Highlight

Use bold and italics inside your text in order to highlight the keywords and new terms and also for

Subheadings
They are eye catchers and make your text easier to read.

5 Review

Visibility
Is all your text visible? A common problem is that you forget to escape reserved characters using "".

Sentences

• All sentences end with a period ".".
• Even those sentences that are used in lists.
• Don't forget to put a verb in your sentence.

Read it again
Read your text again. Read it aloud. You will find a lot of possible improvements.

6 Language Hints

Congratulations you have finished your article. Here some language hints of the most common errors:

Use articles
The most common error. Even if your native language does not know articles, in English you must use them. The reader always wants to know if you are talking about one or several objects, and if you are referring to a specific object or to anyone.

But there are exception where don't use articles:

• Names: Venezuela, John, Marry, Patagonia

• Non-countable things: Liquids, ice-cream, content, information

3rd person
Do not forget the "s" for the third person, also "do" has a third person: "does, doesn't". Also be aware to use "is" instead of "are" when necessary: "There are 3 container types, that are...", "There is one node which is..."

Plural
Don't forget the plural-s. That improves the readability of your article.

Avoid "of"
"of" between two nouns expresses a possession like in "The flag of Venezuela". But in non-possessive case you just put both nouns together:

• "There are several types of action."

• "There are several action types."

• "There are several action types and it is quite simple to plug your own ones."

• "There are several action types and it is quite simple to plug your own types."

• "You have just created a user successfully."

• "You have just created a user."

Real World Example
This sentence has several problems (too long - many thoughts in one sentence, one typo, wrong "one", mixed use of ' and ", 2 different spellings of "backup", needless "is responsible to", no highlighting of keywords, and the worst is that the sentence describes the second event before the first event):

• "That action launches the 'back-up" business process which is responsible to move the content from the production workpsace to the backup one when the publication period ends."

• "That action launches the backup business process at the end of the publication period. The backup business process moves the content from the production workspace to the backup workspace."

7 Page rename dead-lock issue

7.1 Normal

By default, all pages are accessible by every one. After you log in successful, you can edit pages but you can not rename that page if you are not the creator. If you want to rename that page, you have to grant delete right to your username from Access Rights.

7.2 Dead-lock

When granting rights to your user name, you click on edit check box. This means that, after renaming a page, you can not restore your edit right to the default state. To restore it, you have to click 2 times but with the edit right, you can only click on the first time and then you have no edit right to click the second time.