Making your documentation consistent
Always attempt to follow the template set by previous pages in the same parent folders (e.g. if writing a command page ).
Making your documentation useful with hyperlinks
Poorly cross-referenced webpages (especially those on documented) are just annoying and a missed opportunity. Empathize with your audience enough to make sure they can find whatever you talk about.
So an example would be to mention that we have good ETAL BRAT Standards, but fail to link you to that page.
Example 1 - No references
How its rendered: We have good ETAL BRAT Standards.
How its written in markdown:
We have good ETAL BRAT Standards.
Annoying: without references this is vague.
Example 2 - Amateur hyperlink listed but not linked
How its rendered: We have good ETAL BRAT Standards (http://brat.riverscapes.net/Documentation/Standards/).
How its written in markdown:
We have good ETAL BRAT Standards (http://brat.riverscapes.net/Documentation/Standards/).
Annoying: as a user can’t even click on this, they need to copy and paste it into their browser .
Example 3 - Amateur hyperlink listed and linked
How its rendered: We have good ETAL BRAT Standards (http://brat.riverscapes.net/Documentation/Standards/).
How its written in markdown:
We have good ETAL BRAT Standards ([http://brat.riverscapes.net/Documentation/Standards/](http://brat.riverscapes.net/Documentation/Standards/)).
Amateurish: do we need to list the URL out?.
Example 4 - hyperlink only - preferred
How its rendered: We have good ETAL BRAT Standards.
How its written in markdown:
We have good ETAL BRAT Standards We have good [ETAL BRAT Standards](http://brat.riverscapes.net/Documentation/Standards/).
Our default standard.
Back to BRAT Home