Version Controlled Documentation - Editor functionality

Writing articles

Authenticated user with a corresponding role can write articles in ObjectGears HTML editor. Article that is currently displayed can be updated by the user with Editor role after clicking on the pencil icon in the upper right corner of the article.

Editor can create a new text of the given article step by step while original text is still displayd. After the new text is finished, editor can publish it by clicking on button Publish.

Editor can also mark the articles in the following way:

Marking	Article	Article text	Description
Check content	X		The article has to be checked from the perspective of the content correctness (up-to-dateness, accuracy).
Grammar check		X	Article text has to be checked from the grammar point of view.
Translate		X	Corresponding language variants has to be created/updated.

There is field Comment both on Article and Article text level. In the comment fields Editor can describe in more detail what should be corrected or finished in the article re where resources used in the article can be found (for future updates of the article).

Editor can use a page with an overview of all the articles that need follow up.

Editor that shall work on the article can assigned in the article or in the article text.

Connecting articles by links

Articles can be linked in several ways:

1. Related articles can be defined on the article level. These articles will be displayed at the end of the page in the section See also.
2. Links in the article text (targetting other articles or outside of the Version Controlled Documentation - e.g. also webs outside the organization).
3. Links in the article text (targetting another article) defined in form of a bracket command. These can be defined in three way:
   1. bracket command in the link URL - {{AAN,AN0002332}}
   2. bracket command in the article text - link by article number
      {{LinkAN,AN0002335,1.7.1.0,text to display}}
   3. bracket command in the article text - link by article url
      {{LinkURL,session_safety,1.7.1.0,text to display}}

In both cases article (found either by its number or by the text url) of the defined version will be displayed. The text of the link is defined by the last parameter of the bracket command. If non-existing article version is defined or the version is not defined ({{LinkAN,AN0002335,,text pro an}}), article in the current version selected by the user is displayed. The first way always displays article in the version and language according to the current user setup.

The first way differs from the two others because the editor can see, when editing, directly the displayed text and the bracket command is hidden in the URL - it is available only in the pop-up window of the link. Editor writes the text to display, marks the text with mouse, clicks on the icon for entering URL and enters the bracket command into the window that pops up. (Make sure that there is selected  in the combobox Protocol.)

In the second and third way editor writes the full bracket command and it is displayed full to him. In case of many links in the page it is better to use the first way due to better transparency.

Articles can be called also from outside by means of URL in two ways:

1. Your_web/vcd/an/article_number
2. Your_web/vcd/url_of_article_text

     Url can contain also parameters of language and version, e.g.:

http://doc50.objectgears.cz/vcd/AN/AN0001833/v/1.8.0.0?lang=en-US

Wrong links

If we use an erroneous link in the documentation, the users will be (after clicking on the link) redirected to a default article informing them about possible reasons of not finding an article and recommending how to search further. Such an erroneous search will be also logged in the class Erroneous search, data of which we can use to identify and correct erroneous links.

Article text - Name and Name in menu

We are defining Name (mandatory) and Name in menu (optional). Name will be displayed as article headline, it is part of the tag Title and headline h1 (see below). Name in menu will be displayed in the tree in the left part of the screen. In most cases it is ok to define just the mandatory attribute Name and that one is taken over also for display in menu. In the below picture we want to show the long text in the headline and also mention that it is a case study, while for menu we need a shorter text and the fact that it is a case study is obvious already from the name of the parent article in the tree. This is why we define two different texts.

Videos and files

We can attach also videos and files to the article and display them in the page.

Video can be inserted by bracket command {{VideoYT,lwq3ClRfM8U}}:

Files attached to the article text will be displayed either at the end of the page (files inserted into the column Files) or they can be optionally displayed in whatever part of the page (files stored in the column Files in page) by means of the bracket command:

Bracket command	Resulting display	Comment
{{File,Test file.txt}}	Test file.txt	A default file icon is displayed.
{{FileImg,Test file.txt,,ImagesData/Icons/Files/txt.png}}	Test file.txt	The file icon is defined in the command.
{{FileImg,Test file.txt,Text of tooltip,ImagesData/Icons/Files/txt.png}}	Test file.txt	Besides icon we define also a tooltip text.

Inserting highlighted blocks of text

It is possible to insert into the articles also blocks highlighting text with key information to capture user`s attention. This can be done by means of bracket command.

Type	Bracket command	Resulting display
Informace	{{info,Highlighted text with information for capturing user`s attention.}}	Highlighted text with information for capturing user`s attention.
Varování	{{warning,Highlighted text with warning for capturing user`s attention.}}	Highlighted text with warning for capturing user`s attention.
Chyba	{{error,Highlighted text with information of error type for capturing user`s attention.}}	Highlighted text with information of error type for capturing user`s attention.

Inserting characters <  and  >

In order to insert these two characters (angle brackets) we have to use a special bracket command. This is important mainly when inserting examples in HTML or XML. HTML editor will understand HTML or XML text as commands/tags in HTML and begins to execute them instead of normal displaying them. Therefore, any occurrence of these characters have to be encapsulated in double braces before entering them into HTML editor.

Code that we want to display:

<p>Html text</p>

Code that we enter into the article:

Note: The requested display is available to the article reader. In the HTML editor we can see the code including the double braces.

Article tree, language and article version

Article can be created in various languages an versions. Article of the corresponding language and version is displayed to the users according to their choice. User can switch between languages in the upper right corner and between versions in the left part of the screen.

There are Topics in the upper part of the screen. After selecting a Topic (in the below picture it is tab Solutions) tree of articles belonging to the selected Topic will appear in the left part of the screen. User can browse tree of articles and display articles on the same level, child articles etc.

Order of the articles in the left part of the page is given by the article property: Order. If the value Order is not filled in, articles are displayed in the alphabetic order. Order can be used, if the articles under a parent article should be read in a certain order. If the Order is not defined, articles will be displayed in each language in a different order (according to the Name in the given language). If some articles do have order defined and some not, there will be articles with Order displayed first and below them articles without Order value according to the Name in the given Article text.

Article display

Display of articles and their texts depends on several factors:

1. Article is displayed, only if it is marked as Active.
2. Article is displayed, only if the user has selected Version for display, order of which is lower or equal to the article property Last version.
3. Article is displayed, only if there is Article text with property From version, which is lower or equal to version, that the user selected for display.

SEO and optimization for search engines

You can define keywords (meta tag keywords) at the article text and also text appearing as a description in the Google search results (meta tag description). Title of the article is taken from the Name of the article text, same like headline element h1.