Help

Introduction

Openbravo Wiki is an essential tool for online collaboration, allowing rapid growth and centralization of information created by Openbravo community. Mediawiki, a very powerful collaborative web application, is the tool used to manage Openbravo Wiki.

To resolve doubts or requesting help about editing documentation for the Openbravo project refer to our documentation forum.

Editing articles

In this section we explain how you can work on the content of already existing articles or articles that you just have created.

Get registered and validate your email

Before start editing an article you have to be a registered Openbravo Wiki user. If you are not, you have to create an account. Once the account is created is very important that you validate the e-mail associated to the account. You can do that from the user preferences and properly answering the automatic e-mail that Openbravo Wiki will require you to answer to complete the validation process.

Editing the content

This is a quick list of basic MediaWiki style formatting commands.

source code

* first level item
** second level list item
*** and so on

# first level item
## second level list item
### and so on

There is an excellent description of how to Edit pages at MediaWiki web site. Also you have an excellent tutorial on how to create tables on MediaWiki home project page.

Images

To upload a file use the Upload page. This is the page used for example to upload images for articles and referencing them in documents using the Image command. For example, if the image upload is called wizard.jpg you can reference it in your documents including the following tag

[[image:wizard.jpg | description of the image]]

Images are a very common resource in documents. We recommend the following guidelines when working with images:

• Upload images using a 800x600 resolution.
• You can use the resolution parameter in the image tag to specify smaller resolutions from the same source.

Image formats

• For screenshots and icons use PNG or JPEG. They are good and standard formats (always try first PNG as you can apply alpha channels to them), really widespread and web-ready. Avoid the use of GIF (it is limited to only 256 colors), use his replacement (PNG) whenever possible.

• Diagrams, workflows and the likes it's strongly encouraged to use SVG, because it's scalable, you can edit after it has been published and as every other free standard you will never be locked by any software company. Major design software (like Freehand, Inkscape, Dia...) are able to export to SVG.

Font sizes and colors

Mediawiki provides the = symbol to create headers (as already seen in editing the content). Headers have different font sizes.

A font size can be also specified using html attributes:

<font style="font-size: 110%"><font style="font-size: 110%">110% text</font></font>

Note that we strongly discouraged to do so since it breaks formatting. Use only on really needed cases.

The same policy applies to colors. To change text's color:

<font style="color: #51990F;"><font style="color: #51990F;">Openbravo green color</font></font>

Allowed colors

To allow a better readability of our wiki, we encourage every editor to strictly use only these colors:

Avoid using HMTL

MediaWiki systems use their own mark up language to give format to text. In the section Editing Content of this document, you have a description of how to use this formatting markup. You also can use the MediaWiki quickbar that is at the top of the editing window when creating your articles to give format to your text.

Please, avoid using HTML tagging, including tables since they are not the standard way of coding styles in Mediawiki systems.

Templates usage

Templates are used to put the same kind of content in pages. Like the Language header or the rating poll.

These are the templates used at Openbravo's wiki:

• Template:!
  • Template used as a hack to be able to add a | in a template
  • Call it like {{!}}
  • See in action in:
• Template:(!)
  • Template that creates an information box with a light icon and the text that it's passed with the template as a parameter
  • Call it like {{(!) | Some text}}
  • See in action in: Functional Documentation/MRP#Material Requisitions
• Template:BugReference (deprecated since we migrated to Mantis)
  • Template to link to an existing bug in our Sourceforge bug tracker.
  • Call it like {{BugReference | bugnum=sourceforge bug number}}
  • See in action in: OB 2.34 ReleaseNotes#List of bugs fixed in this release
• Template:BugReferencePOS (deprecated since we migrated to Mantis)
  • Template to link to an existing bug in our Sourceforge bug tracker for Openbravo POS.
  • Call it like {{BugReferencePOS | bug=sourceforge bug number}}
  • See in action in: Openbravo POS 2.10 Release notes#Bugs_fixed
• Template:CodeSnippet
  • Template used for Code Snippets
  • Call it like {{CodeSnippet | name=Code Snippet name | version=Version number | author=Your Name}}
  • See in action in: PrintButtonExample
• Template:Deprecated
  • Template to mark a page as Deprecated, i.e. the page's contents are no longer useful. It will display an informative box
  • Call it like {{Deprecated}}
  • See in action in:
• Template:FunctionalSpecifications
  • Template to create functional specifications for Community Projects, look at the template page to see which parameters allows. (The ones marked with {{{name}}}
  • Call it like: (see examples below)
  • See in action in: IBAN Specifications, PO for translations or any other page in this list.
• Template:IssueReference
  • Template to link to an existing bug in our Openbravo mantis bug tracker.
  • Call it like {{IssueReference | issuenum=issue number}}
  • See in action in: OB 2.35 ReleaseNotes/MP5#List of bugs fixed in this maintenance pack
• Template:Localization
  • Template that creates a box for information about localizations projects.
  • Call it like {{Localization | country=Country | leader=Language Leader name | status=Localization status}}
  • See in action in: Localization Projects
• Template:RatingArticle
  • Template used to rate articles in our wiki.
  • Call it like {{RatingArticle}}
  • See in action in: User Manual 2.3
• Template:RequestDeletion
  • Template to request a page deletion. Useful if you don't have permissions to delete pages.
  • Call it like {{RequestDeletion}}
  • See in action in:
• Template:TranslationComplete
  • Template used to mark translations as finished.
  • Call it like {{TranslationComplete}}
  • See in action in: Localization Projects
• Template:TranslationNeedsReview
  • Template used to mark translations as needs review status.
  • Call it like {{TranslationNeedsReview}}
• Template:WorkInProgress
  • Template used when a page isn't finished, so you can advice other visitors or contributors that you plan on finishing it.
  • Call it like {{WorkInProgress}}

You have more information on templates at Mediawiki web site.

Redirect an article

To have one page to redirect automatically to another one (fore example User Manual points to User Manual 2.2) just put only this text in the article:

#REDIRECT [[page to redirect to]]

Creating new articles

Make sure the article does not exist

Before creating a new article make sure that the article or a similar article already.

• Try using the search box in top right to search for similar articles.
• Review the list of all articles. Take into account that the article might have a title different to what you might expect or that it might be part of a longer article.

Before to start a new article, please consider if you can enhance an already existing article.

Choose a category and title

Articles are organized in categories. You can choose an existing category or think of a new one. But think that it is easier for people to find articles when there are the minimum number of categories.

Once you have the category think of a good name. It is recommended that is not too long but it clearly states what the content of the article will be. That will help whoever reads the article to know what you really want. You can also help by adding a short description next to the title.

Create the article

To create a new page just put the new name of the page in the URL. For example, to create a page about How to Install introduce the following URL in your browser:
http://wiki.openbravo.com/wiki/How_To_Install, and then select the Edit option to create a new page.

Get informed when someone modifies the article

When editing a page of the wiki guide there is a checkbox just above the buttons that says Watch this page. If you select it you'll receive a message whenever someone writes to it or its discussion page.

It is suggested that you watch all the pages that you write or to which you make significant contributions so that you are aware of the changes made.

Translating documentation

In the Openbravo project most of the documentation is at the project's Wiki. This allows people to modify and enhance the documentation, but also allows every one to translate the documentation into their language.

Mediawiki supports different multilingual strategies. At Openbravo's Wiki we use the ISO-639-1 language code.

Naming documents

For naming documents we use the format document_name/iso_639_code. For example, the name of this help page in English is:

http://wiki.openbravo.com/wiki/Help

In French is:

http://wiki.openbravo.com/wiki/Help/fr

Where fr the ISO-639-1 code for French.

For German is:

http://wiki.openbravo.com/wiki/Help/de

Where de is the ISO-639-1 code for German language.

Adding the following template to your a Wiki page:

{{Language | Page name}}

will create the necessary links to access the same pages in other languages.

Naming images

For naming images the same guidelines are followed. Just add an underscore plus with the language code plus an additional underscore plus the country code.

For example, installer.jpg becomes installer_de.jpg for the German version.

Naming categories

For naming categories the same guidelines are followed. Just add a underscore plus the language code.

For example, the category UserManual_10 becomes UserManual_10_fr for the French version.

Important recommendations

Please, when translating Wiki documents remember:

• Create new pages, images and categories by adding the language code to its original English name. Using the same name overwrites the original English version.

• Do not translate the name of new pages, images and categories. They should remain in English.

• When translating documents it is strongly recommended to translated from English to your language. Almost all the Openbravo ERP documentation is written originally in English and translating from an already translated version usually produces poor results.

• When translating the user manual or any other user documentation check if Openbravo has been translated into your language. It is very important to use the same translations than the ones used in the application, if not you may be referring to the same options using different names.

Consolidating and splitting articles

Consolidating documents

When creating a new document we suggest to keep all the content on a single page whenever is possible. We recommend this because:

• You can print them directly. If you want to print a fragmented document you have to print several documents. It is possible to create a Single View to print them but this has to be manually created for every document and manually maintained, which does not scale in the medium term if you have many documents and also in many languages.
• When you search you get lots of results from small documents that are not relevant making more difficult to find the information that you are looking for. Having single documents with all the information results in better searches.
• When fragmenting documents you end up having dozens of documents in a category, most of them are not useful by their own to users since they are really part of other documents. Categories become less useful since they contain lots of noise. Even if you manually edit them.
• The Wiki gets more difficult to maintain since you have lots of pages. In the medium term, the pages that are not properly linked (it happens often), ending up with orphaned fragments of documents that you do not know to what document originally they belonged to.

Split articles

In the other side, for really long articles is difficult to keep track of changes. The best solution is to split the article in long parts. It can be done creating as necessary subarticles as needed with the following scheme:

If the main article is User Manual 2.2 each subarticle must be User Manual 2.2/Menu Functions or User Manual 2.2/System Admin.

That way it will be more easy to know how many subarticles an article has, to keep articles organized and to allow more than one page with the same name (i.e the same pages for different User Manual versions: User Manual 2.3/User Interface and User Manual 2.40/User Interface).

Single views

But the other way around it's useful sometimes.

For example, to print or export to other formats the User Manual you will have to go to each page and print/export them.

The best solution here is creating a single page view of an article and its subpages.

To achieve this, Wikimedia provides transclusion, which is resumed by "include the content of page(s) to create another one with their content but without duplication of text".

To include multiple pages in another page use this syntax:

{{User Manual/First page}}
{{User Manual/Second page}}
...

Examples in User Manual 2.2 Single Page View or User Manual 2.3 Single Page View.

Note that this is the syntax used for templates.

Style Guide

This is a list of recommendations for using the different formatting styles in documents.

Article titles: Use titles that reflect the content and preserve the spaces between words (i.e. Installation_Guide instead of InstallationGuide)

Titles: Capitalization and spaces between words, start with two equals headers and add more as you need subtitles (up to 6 equals)

Bold: Use only when necessary, i.e. formatting some text in bold is to remark it, but it looses this effect if an entire paragraph is bold.

Italic: Use it for quoting texts or describing a UI navigation path (i.e. go to General Setup > Application > Background Process)

Tables: Use only allowed colors and keep in mind that a wiki is for content not for visual presentations. To add a border around it start the table with:

{|border="1" cellpadding="5" cellspacing="0" 

The cellpadding and cellspacing are optional, but try to keep them logical (i.e. don't make a table with cellspacing="500")

Formatting: It's not a good practice to use the

preformat style to create headers

use the equal signs (==) instead

Links: Do not use the text click here. See W3 recommendations.

Name guidelines: Use Openbravo ERP and Openbravo POS (with space between Openbravo and ERP/POS).

More information

• Media Wiki help pages.