Good practices - AtlasOfLivingAustralia/documentation GitHub Wiki

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 : [email protected])

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