Writing Documentation

top

Writing Documentation

General
Specific

Formatting Documentation

HTML
codetables


General Guidelines

Documentation should be written to provide users an understanding of the concepts and general data structures which make Arctos work. Arctos seldom has only one way of accomplishing any given task, so “when A then click button B” instructions should generally be limited to collection-specific documentation. Most forms in Arctos are data-driven and may therefore appear different to every user; keep this in mind when giving examples.

Formatting Documentation Code

The following describes the conventions and tags used in the WordPress Arctos documentation. It’s not going to be very instructive unless you’re looking at the edit HTML view.

View HTML and scroll up to see the page navigation tools.

The first thing on every page should be an anchor named “top”:

Next is the page-nav div. Don’t forget closing tags.

This is a title

this is anchor1
this is anchor2

This is another title

this is anchor3
codetables

Content goes down here.

bla

bla

stuff

There’s no reason to have an anchor on the first block of text.

Top
Now, we’re down far enough that anchors are beneficial.

The anchor is also a hyperlink to anchor #top.

Bla bla bla

Top

SomeTable . SomeField
SomeDataType nullable

above is a field definition – given the anchor name, it should be for field “anchor2.” Note the spacing and order – important for WordPress’s half-baked pseudoHTML-thingee.

Said half-baked thingee loves fracking up links, so watch for things like

Top

Note the linked text is now magically outside the tag. Sweet. Something about switching back and forth between “visual” and “html” editing, maybe. Or sunspots.

Top
Yet another anchor. You can link to anchored WordPress content by

http://theBaseUrl.com/any/directory/structure/#anchor1 – e.g,

404; anchor1

or locally – within the current page, with simply #anchor1

anchor1

Top
Codetables is going to get the bold treatment. Spiffy, and probably how these things should all look.

Do NOT discuss code table values in this documentation – that belongs only in the documentation field of the table itself. Instead, link to that, like this:

link to code table

And then, only if necessary, elaborate on anything that cannot be fully described in the code table.