This article is aimed at all those who write in the GeneXus Community Wiki.
It gives you specific guidelines and patterns to write with the same criteria. Therefore, here you will find the decisions taken for the style of writing in the documentation.
Community Wiki documents should be written preferably in English (American English).
The writing style is the same as Google's way of writing and Microsoft's way of writing.
You have to write to the reader in the second person (you). So do Google and Microsoft.
The public of the GeneXus Community Wiki, in general, are developers, so you write "you" to developers' readers. If you need to differentiate developer from end-user, you have to take that into account.
" When you download the setup, ..."
"When pressing the F5 key, ..."
This link provides more examples and useful alternatives to writing in the second person.
Example #1
"Let’s suppose that a company sells products and offers services."
"Suppose that a company sells products and offers services."
Example #2
"Let's see an example."
"Look at the following example."
Avoid writing "we... " / "our..."
Example #1
"As we know, there are many ways to..."
"There are many ways to..."
Example #2
"Our objective is..."
"The objective is..."
Example #3
"We have the Prize Transaction which allows defining rewards to be traded for miles."
"The Prize Transaction allows defining rewards to be traded for miles."
Example #4
"We call users’ views to the descriptions given by the users who need the application, about their reality and requirements."
"The concept of users’ views refers to the descriptions given by the users who need the application, about their reality and requirements."
Important considerations when writing documentation
1) In the first sentence, you always have to write the objective or the definition of what you are documenting (what it is for).
2) Put yourself in the reader's place. If you were the reader of what you are writing, what would you need to be told? What is important and what is not? In what order is it friendly to read it?
3) Describe one idea per paragraph. If there’s more than one, split the paragraphs.
4) If your paragraph contains a list of any type, convert it to a bulleted list.
Example:
Quickly read this:
The User Control object offers the following benefits: It provides the possibility to define User Controls in a built-in way into the Knowledge Base. Also, it allows you to base its appearance on a style provided by a designer, CSS Framework, etc. Besides, it generates a server-side HTML code, which means power, since it is easier to scale a server than the clients.
Now quickly read this:
The User Control object offers the following benefits:
- It provides the possibility to define User Controls in a built-in way into the Knowledge Base.
- Allows you to base its appearance on a style provided by a designer, CSS Framework, etc.
- Generates a server-side HTML code, which means power, since it is easier to scale a server than the clients.
Both contain the same content. However, the second form of writing helps you better understand the information in less time.
5) If your paragraph contains steps to follow (i.e., to set something), convert it to a numbered list. It may be clearer to describe steps (Step1, Step2, Step3) instead of writing paragraphs that start with the words "First", "Next", "Then".
6) Use headings properly. Structure your writing with headings.
7) It is vital to write always the exact names of the properties, methods, controls, etc.
Additionally, you should link the property name with the page which defines it.
Examples
Auto-number property
Autonumber property
Query Viewer control
QueryViewer control
Why?
- To provide precision to the reader.
- To be coherent and professional.
- To help the reader to find it inside GeneXus without doubts.
8) When writing an article about a property, method, event:
Do not start like this:
- This property allows you to...
- This property is used to...
Start like this:
- Determines...
- Sets...
- Names...
- Describes...
Why?
- To explain what it is for in a direct way.
- The GeneXus Community Wiki is integrated with the GeneXus IDE. This means that if you are working with the GeneXus IDE, and you right click on the name of a property, and then you select Show Description, you will see the first sentence of the property article:
- Note: When writing the short description of a property, method, function, or command article, it is suggested not to include a link as it will not be shown correctly in the GeneXus IDE´s description.
9) When you need to indicate a sequence of options the reader must select, use the following writing style:
File > New > Object.
Do not use other writing styles (in order to maintain coherence):
File / New / Object.
File - New - Object.
10) The examples always help to finish understanding the explanations. So, try to include an example of use.
11) Please, apply the Syntax conventions.
12) When writing an article, it is a good practice to select the correct keywords. For example: take into account the use of words that indicate levels of requirements, such as: "Must", "Must not", "Should" and "Should not". Read more about it at Key words to Indicate Requirement Levels.
13) You can find tips and frequently asked questions about the edition of GeneXus Community Wiki pages at Wiki Editing - Tips and FAQ.
- Grammarly is a spellchecker that helps you wherever you write on the web. So, it will help you when you are editing GeneXus Community Wiki pages.
- Hemingway is another application that allows you to paste a paragraph and it detects different kinds of errors in your writing. It also suggests how to improve them.