Wiki usage conventions

For in-line commentary

Some documents on the wiki have an overall structure that is essential to maintain relatively statically. The documents related to the iRel interface design are a good example. Nonetheless, various developers need to be able to comment on the material within such documents and this commentary needs to be maintained.

We will use wiki footnotes for this purpose. This allows us to keep all commentary related to a given document on the same page at the bottom of the document. We adopt the following wiki usage conventions in marking up such documents with developer commentary...

  • When you need to add a comment related to a sentance/paragraph/section of the document for which a footnote does not already exist...
    1. Add a paranthetical statement at or near the sentance/paragraph/section like so (see footnote[N]) where n is some integer chosen to uniquely identify it from among other footnotes. Note, there is no space between the word 'footnote' and opening [ of '[n]'.
    2. If there are not already any footnotes on the page, add an h1. Discussion Notes heading and an extra blank line underneath it.
    3. Add a footnote to the bottom of the page using fnN. *Note:* where N is the same integer used in step 1.
    4. Add your comment(s) leading with your name or initials in bold as in *Tim T.:* here is what I think
  • When you need to add a comment related to a sentance/paragraph/section of the document for which a footnote already exists...
    1. Locate the associated footnote at the bottom of the page (e.g. follow the see footnote link)
    2. Add your comments leading with your name or initials in bold as in *Tim T.:* here is what I think

For example...

Here is a line to which a footnote has been added (see footnote3). Note '3' was chosen arbitrarily.

Discussion notes

3 Note 3:

MCM: Mark miller added this footnote