Good practices

Architecture of a wiki page

A new page must respect the following rules :

• Header 1 are not used, you need to start with Header 2 (##)

• The edit mode need to be in "Markdown"

• The wiki is order by themes so before you create or edit a page, be sure that the informations you wish to add is on the right section

• If a specific documentation of one aspect of the ALA project is already existing on Github, just point that specific documentation with a link insert into a page on the right wiki section (see Image service or ALA4R for example).

• On your pages, if they are instuctions, include at least one screenshot by part page.

• When there are too many informations on one page, create a Table of content of the page. A table of content is only composed of link to the different part of the page.

• If you wish to re-order the wiki by moving pages between the sections or to add/remove a section, please contact the head of the documentation first (Caviere Fabien, GBIF France : caviere@gbif.fr)

If you have any question about the wiki, feel free to contact the head of the documentation

Editing's rules

• Always specify an "Edit Message". This way, other people will understand more easily your modifications

Rules of text formating

• Prefix your part title with '## '

• Prefix your section title with '### '

• Prefix your paragraph title with '#### '

• Don't forget to add 4 spaces or one tab before any code line

• When you have multiple solution, use the following pattern :

  ---

  SOLUTION 1 :

  text

  text

  ---

  SOLUTION 2 :

  text

  text

  ---

• For the page on the "Portals in production" section, respect the following structure :

  1. an introduction : informations like
     • metadata on the portal development (number of developers and time allowed to the portal for instance)
     • the structure that host the portal
     • the portal architecture
     • who, what, how, when and where
     • stats
     • specification
  2. a diagram
  3. the mains local points to this portal

Tips

When you create or edit a page, you can display the help block: it will show all the information you need to know about text formatting