Riverscapes Consortium

Consistency & Utility

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

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.

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 .

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

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 ETAL Standards Back to Help Back to BRAT Home