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.

If you have any questions about editing documentation for the Openbravo project refer to our documentation forum.

Wiki content

This wiki is focused on content about Openbravo ERP and Openbravo POS. It's not for personal notes and the likes.

Set the correct date and time

To set the correct date for your current timezone, go to Preferences → Date and time and click the Fill in from Browser button to add the correct offset.

This is really useful if you look at the Page history or Recent Changes pages, so you will see the correct date and time.

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.

Edit with OpenOffice.org

If you don't like to edit inside the browser you can grab the content from the editing page, save in your computer as plain text (extension .txt) and then edit it with OpenOffice.org. When you have made your changes you can then export the document ( File → Export → File type → MediaWiki txt) and paste it again to the editing 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%">110% text</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:Fancydancy
  • Template to create fancy boxes with any kind of text inside.
  • Call it like {{Fancydancy|Some cool text}}
  • See in action in: Openbravo environment installation
• 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 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 Install translation points to Translating Openbravo#Installing a new translation) type only this text:

#REDIRECT [[page to redirect to]]

You shouldn't use always a redirect. For minor articles you can safely remove the old article and update all the links that pointed to the old article to the new one. For main articles always keep the redirects.

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.

Titles

To have a consistent naming across our wiki we recommend some guidelines when choosing a new title for your article:

• Ensure that there isn't any similar article already in our wiki, if there is, try always to contribute to that article
• Only capitalize the first word
  • i.e. Openbravo environment installation instead of Openbravo Environment Installation)
• Use spaces between words
  • i.e. Openbravo environment installation instead of OpenbravoEnvironmentInstallation or Openbravo_environment_installation
• Make sure the title describes correctly the content
  • i.e. Openbravo environment installation instead of Installation (of what? for who? ...)
  • But don't explain all the content in the title itself! A four or five words title is better than a ten or even more words, it helps to get concise names so they can be remembered.

Create the article

To create a new page just go to Create New Article and add the desired name in the box and push the button Create New Content

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.

Document versioning

Sometimes you need to have different documents for different versions of a product. For example, we have different documents for the Openbravo ERP user manual 2.30 and 2.40.

Our version policy is:

• For product related documents, specially manuals, we recommend to use different documents names reflecting the version on as part of the document name. For example:
  • User_Manual_2.30 for Openbravo ERP R2.30 user manual
  • User_Manual_2.40 for Openbravo ERP R2.40 user manual
• For the rest of the documents:
  • When adapt them to reflect more than a version require only small changes, just indicate so in the document. We are already doing so in the Openbravo ERP Specifications document for example.
  • For documents that change significantly follow the same naming convention that we recommend for product related documents.

Preventing editing conflicts

Editing conflicts are irritating and time-consuming. Anyone that has worked in a Wiki system for some time has suffered them.

There is no basic rule to avoid editing conflicts, my suggestions for preventing them are:

• Use the Edit button in the sections, instead of the Edit button (that edits the whole page) for editing documents. MediaWiki handles merging much better when merging only sections since it reduces the area of the conflict.
• Make sure that you do not block the document for long periods of time.
• Make sure that your document is properly written correctly, formatted and categorized. This will reduce the chances of been edited by editors and other users.

Translating documentation

See Starting Guide for Wiki translators.

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")

Lists: It's not mandatory to finish each line in a list with a dot, but use the same rule in all the elements' list.

• This list.
• looks
• a little.
• weird

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).

Documentation style guide

If you are writing an article about documentation make sure that you read our Documentation Style Guide.

Functional specification style guide

If you are writing an article about functional specification make sure that you read our Functional Specification Style Guide.

Spaces and newlines

Please add a blank line before each header section (the lines that contains the equal signs and a few words inside them):

(...)Last line from the previous section.

=== Some title ===
First line from the next section(...)

For lists add a blank line before starting the list (keep in mind that between list elements it can't be any blank line), another one after the list and a space between the * or # and the text:

Some introductory text before the list:

* First element of the list
** more elements
* Last element

Text after the list

Also add a blank lines before and after images and between blocks of text.

For example this text:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Image:Loremipsum.svg
==== Header Lorem Ipsum ====
* List
** Lorem
** Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Some other text

Should be modified like this:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
 
Image:Loremipsum.svg

==== Header Lorem Ipsum ====
* List
** Lorem
** Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Some other text

More information

• Media Wiki help pages.