A few Openbravo wiki guidelines

Hi all!

To ensure our wiki is properly maintained we need to ensure that everyone knows how to edit it.

So, the objective of this blog post is to highlight some of the frequent mistakes or not-known features that some of you do while editing our wiki.

Internal links

To link from one article to another article in our wiki just write:
[[Article-name | some text]]
i.e: [[Openbravo community installation | installation guide]]
The "| some text" part here is optional, it will be the text shown as a link.

The most commmon mistake here is to add the full URL, i.e.:
[[http://wiki.openbravo.com/wiki/Openbravo community installation | installation guide]]


Preformatted text

To make preformatted text (i.e. the grey brackground text like in:
http://wiki.openbravo.com/wiki/Openbravo_environment_installation#Gentoo ) just put a space BEFORE the text:
like this

Or if it's really required you can use some <pre>text</pre> format, but try to use the other option, it's less typing and more the way that the wiki format says.


Templates

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

There are lots of them:
http://wiki.openbravo.com/wiki/Special:Uncategorizedtemplates

Some help about how they work:
http://wiki.openbravo.com/wiki/Help#Templates_usage

Try to use them as much as possible (and when applicable!), not just because is less typing, but also because if, for example, we have to change our bugtracker we will just need to change the template and everything will work, hardwritten links to the bugtracker will be broken.


Categories

Categories are used to group articles by their kind of information (Community, Development, OpenbravoPOS ...) and having a good categorisation is key to have better searches and better organisation.

Please try to add at least one category at every new article. If you don't know in which category belongs an article surf the categories and try to find articles on the same topic as the one you have written and use the same category.

All categories:
http://wiki.openbravo.com/wiki/Special:Categories

To add a category to an article just type at the bottom of the article:
[[Category: Category-name]]


Italic and bolds usage

To make some text italic just type:
''some text'' (double single quotes :)

To make some text bold just type:
'''some text''' (triple single quotes :)

Use italic when you are referring to UI text, citation texts, file names, object properties, etc etc

Use bold carefully. Bold text is used to highlight some ideas or important statements, but are useless if a whole paragraph is bold. Look at the final examples to see what I mean.


Images

You know: An image is worth 1,000 words.

Just be sure to read the Images section in our help:
http://wiki.openbravo.com/wiki/Help#Images

If your are drawing a diagram make sure to upload as a .svg format (every professional diagram-based editors). Everyone will be able to see it (since it's a standard format, not a proprietary one) and more importantly if someone (like me) has to modify or update it he/she will be able to edit it directly without having to make it again from scratch.


Titles

For title choosing see our Help:
http://wiki.openbravo.com/wiki/Help#Titles

Also for translators:
http://wiki.openbravo.com/wiki/Help#Translating_documentation


Blank lines, spaces and usability

In Mediawiki (the wiki software) when you make a line break it just ignores it. So it's only useful while editing the article.

To make a new paragraph you have to add a blank line between the two paragraphs.

So, my plan (as you can see as from Monday and further edits) is adding two blank lines before any new section title (i.e. any line that has some text surrounded by equal signs ===== text ==== ) and another one after the title.

For better readability add a new blank line before and after a list (the lines that start with * or #) and a space between the character (# or * and the start of the content). For example:

# One
# list
# that's
# easy
# to
# read

It's quite a challenge to find anything in less than 30 seconds in a wiki edit box if there isn't any blank link anywhere :)

As a maybe not really useful for readability purposes, but necessary for better browse-ability, try to make the lists without blank lines between elements, not just because if you separate them they create a new list for each element, instead, think about a blind person, if he is reading something like this:

Openbravo enhancements for the next release, see the list below:

* New modularity system

* Better integration with BI
...

As a last note in usability, some of you are already doing it, so for the few of you that doesn't add it, please, add a cellpadding="5" to the tables, so they will be a little bigger, but will be better readable.

Just modify the header:

{| border="1"

with:

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


User talk pages

From now on to ping someone to discuss something, to thanks him/her for updating an article or ask the administrators to give you advice, use the personal talk pages.

A personal talk page looks like (just change my user name for the user you want to ping):
http://wiki.openbravo.com/wiki/User_talk:Gforcada

Just a small recommendation when editing a talk page: always end your message with --~~~~ (or click the second button starting from the last one - from left to right- and it will add it for you).

With this little syntax you will add your user name and a timestamp, so when you take a look at someone has said something in your talk page you will see how many time has passed from that day.


Style guide and more help

Make sure you read, at least once, our Help page:
http://wiki.openbravo.com/wiki/Help

And the style guide inside it:
http://wiki.openbravo.com/wiki/Help#Style_Guide


Final examples

Just two visual examples (and as I said it's not anything personal) that I came across this Monday:

First:
before:
http://wiki.openbravo.com/wiki/index.php?title=Openbravo_ERP_installation&oldid=15728
after: http://wiki.openbravo.com/wiki/Openbravo_ERP_installation

Second
before:
http://wiki.openbravo.com/wiki/index.php?title=Projects/Project_Service_Management_Review/Development_Status&oldid=13442
after:
http://wiki.openbravo.com/wiki/Projects/Project_Service_Management_Review/Development_Status


Thanks for reaching this point! I hope from now on everyone will have a better understanding about how our wiki works :)

Regards,
Gil Forcada