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 contact Openbravo at "patricia.sanjuan@openbravo.com" email account.

Wiki content

This wiki is focused on content about Openbravo, that is Openbravo Business Edition and Openbravo POS, that is Openbravo Commerce Edition. 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.

Openbravo User Guide edition

Openbravo User Guide is protected against manual editing because it is automatically generated from Openbravo meta-data.

If you want to change any user guide wiki article you can only make those changes in the "ManualDoc" sections.

You can use "View Source" option to take note of the "ManualDoc" you need to modify.

After that you just need to edit and update the corresponding wiki article on the url: wiki.openbravo.com/wiki/ManualDoc:XXXXXXX

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

The account created will only have read permissions, to have write permissions you have to write a mail to "staff (dot) rm at openbravo (dot) com" asking for them.

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 | 900px | 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.
• Always re-size an image to fit well the page width. Typical width to use is 900 px (see example above) but it can be adjusted in particular cases to look consistent with other images.

Please refer to Media Wiki Image Help to discover more information about image syntax when editing the wiki.

Image formats

• For screenshots and icons use PNG or JPEG. They are good and standard formatS, really widespread and web-ready; always try PNG first as you can apply alpha channels to them. Avoid the use of GIF (it is limited to only 256 colors), use its 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.

Email address format

Use words in square brackets [] for the dot "." and at "@" signs.

Example: for the following address: name.surname@openbravo.com use:

name [dot] surname [at] openbravo [dot] com

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 this only in when you really need to.

The same policy applies to colors. To change the text 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 HTML

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

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

Highlight the code

If you need to add code snippets in your articles make sure you place the <source lang="XXX"> tag before the code and the </source> tag after the code (where XXX is either java, css, html, xml ...).

For example an xml snippet will display like:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="admin" password="admin" roles="admin,manager"/>
</tomcat-users>

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 {{!}}
• 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: Process_Example
• 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}}
• Template:Fancydancy
  • Template to create fancy boxes with any kind of text inside.
  • Call it like {{Fancydancy|Some cool text}}
• 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}}
• 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}}
• Template:AvailableFrom
  • Template used when a new feature is documented in the wiki.
    In that case, it is important to indicate the Openbravo starting version, a feature is available from.
  • Call it {{AvailableFrom|3.0PR14Q4}} , and remember to specify the correct Openbravo version that includes the new feature.
• Template:DeprecatedFrom
  • Template used when an old feature has been deprecated and is documented in the wiki.
    In that case, it is important to indicate the Openbravo starting version from which the feature will be deprecated
  • Call it {{DeprecatedFrom|3.0PR14Q4}} , and remember to specify the correct Openbravo version that includes the new feature.
• Template:Warning
  • Template used when an important warning must be communicated to the reader
  • Call it like {{Warning | Some text}}

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, does not already exist.

• 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 (see their hierarchy). You can choose an existing category or think of a new one. e.g.[[Category:Development ERP]]. 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 is not any similar article already in our wiki, if there is, try always to contribute to that article
• Use always English for titles, even if you are planing to start a document in Spanish or any other language.
• 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 the contents correctly
  • 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

Use hierarchies for large articles

Openbravo's wiki has installed the Hierarchy extension which enables wiki contributors to create well defined hierarchy content for bigger documents (i.e. the user manual or the developer's guide).

To use this extension only 2 steps are required:

Create the hierarchy index

Create an empty article with the hierarchy index. It should look like:

<index>
[[Sample Top page]]
= Sample Chapter one =
== Sample Topic one ==
== Sample Topic two ==
= Sample Chapter two =
== Sample Topic three ==
=== Sample Subtopic A ===
=== Sample Subtopic B ===
== Sample Topic four ==
</index>

Where all lines in-between the equal signs are subpages (they can be indented like sections in an article) and there is a top page (in the example above the [[Sample Top page]]) which can be used for explaining the manual/guide, give some advices, show in which status is currently the manual, etc.

Add the hierarchy index to the articles

In each article it just has to be added the header an footer sections:

{{Hierarchy_header}} 
Article's content
{{Hierarchy_footer}}

So, just wrapping the content of the article with the header template and footer template is enough.

For a complete list of what can be achieved and what can not be done see the extension usage documentation.

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. This our recommended policy.

For product related documents, such as manuals or release notes, we recommend to use different documents names reflecting the version on as part of the document path. For example:

• ERP/2.50/User_Manual for Openbravo ERP R2.50 user manual.

And having a page index for all the related documents like the main page for Openbravo ERP 2.50.

We use the prefixes:

• ERP for Openbravo ERP
• POS for Openbravo POS
• ERP_Network for Openbravo ERP Network
• POS_Network for Openbravo POS Network

For the rest of the documents we recommend:

• 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 loses this effect if an entire paragraph is bold.

Italic: Use for quoting texts or describing a UI navigation path (e.g. 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 period, 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.
File: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.
 
File: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

Categories

The categories are designed to be useful to users navigating the content of this site not to Wiki administrators. For example, if you have a document with multiple pages only the index page of the document should be categorized. Following this policy, when the user looks at the category finds documents useful to them not just list of pages that belong to a category.

This the current list of Categories for Openbravo Wiki:

• Openbravo ERP
  • Architecture ERP
    • Architecture Legacy ERP
  • Community ERP
  • Development ERP
    • Code Snippets ERP
    • Database Model ERP
    • Development ERP 2.40
    • Development ERP 2.50
    • Release Management ERP
      • Release Notes ERP
  • Documentation ERP
    • Configuration ERP
    • Datasheets ERP
      • Datasheets ERP 2 40
      • Datasheets ERP 2 50
    • Functional Documentation ERP
    • Installation ERP
    • Tutorials ERP
      • Alternatives Tutorials ERP
      • Business Workflows Tutorials ERP
      • Operations Tutorials ERP
    • User Documentation ERP
      • User Documentation Legacy ERP
  • General Information ERP
  • Localization ERP
    • Chart of Accounts ERP
  • Projects ERP
    • Abandoned Projects ERP
    • Complete Projects ERP
    • Current Projects ERP
    • Future Projects ERP
    • Openbravo ERP 2.40
    • Openbravo ERP 2.50
    • Openbravo ERP 2.60
  • Quality Assurance ERP
    • Acceptance Test ERP
      • Acceptance Test Scripts ERP
    • Automated Testing ERP
    • QA Processes ERP
    • QA Test plan ERP
      • QA Test plan 2.40 ERP
      • QA Test plan 2.50 ERP
    • QA Tools ERP
    • Upgraders Testing ERP
• Openbravo POS
  • Community POS
  • Configuration POS
  • Development POS
    • Code Snippets POS
    • Release Notes POS
  • Documentation POS
    • User Documentation POS
  • Installation POS
  • Localization POS
  • Projects POS
  • Quality Assurance POS
• Openbravo ERP Network
  • Release Notes ERP Network
• Administration
  • Deprecated
  • Legacy
  • NeedsAttention
  • Templates
  • WorkInProgress
  • Redirect
• Community
  • Collections
  • Community ERP
  • Community POS
  • Methodologies
• Languages
  • Basque
  • Catalan
  • Chinese
    • Chinese Legacy
  • Chinese (Taiwan)
    • Chinese (Taiwan) Legacy
  • Dutch
  • French
  • German
  • Italian
  • Japanese
  • Polish
  • Portuguese
  • Russian
  • Spanish
    • Spanish Legacy
  • Turkish

Comments:

• The name of the categories have to be unique. You cannot have for example a category called Development as subcategories of Openbravo_ERP and Openbravo_ERP. As Openbravo POS projects grows, we will keep hitting this problem more often. For example, if we once want to create a Release Managment Openbravo POS category we will discover that there is already one for Openbravo ERP and we will have to rename the old category to Release Managment_ERP and then recategorize the content. To avoid this, we add _POS and _ERP as suffixes in the category name.
• If the need arises we will duplicate the trees for every language like Openbravo Documentation_POS->User Documentation_POS below Spanish.
• In the case that a document is shared by more than one project, like the Development Process document, multiple categories will be used.

If you need new need categories please contact the Wiki administrators.

Wiki Archive namespace

Openbravo Wiki has hundreds of articles. Many of these articles are legacy documents that belong to older versions of our projects: user manuals, design documents, old coordination documents, etc. A search in Openbravo Wiki returns as result many legacy documents that are no longer useful making more challenging for users to find the information that they are looking for.

To address this situation, there is a Openbravo Wiki archive namespace where all the articles that we consider legacy are moved. The idea is to keep in the main namespace only documentation that is valid for the current stable version and the version immediately previous.

Additionally, when a document is moved to the Archive namespace, the categories that are not version specific are removed. For example, in a document with the categories General and Openbravo ERP 2.50, the category General will be removed but the Openbravo ERP 2.50 will be kept.

More information

• Media Wiki help pages.