Contributing Documentation

Contributing Documentation

There are two types of documentation used in the Integra project: written documentation and screencasts. All documentation should be clear, concise and focused.

Screencasts

• no more than 5 minutes in duration
• no more than 1000×600 pixels in size
• use the H.264 video codec at High Quality
• use Stereo audio at 96 kbits/sec

We recommend the Screenflow application for Mac.

Written Documentation

• use Plain Text formatted using Markdown syntax
• include images to illustrate key points
• names of views and other UI elements should be capitalised as they are in the GUI. Examples Info view, Arrange view, Module view
• Other Integra-specific terms should be written in italics. Examples: edit mode, module, block, track
• any Integra-specific names should be written in bold by placing a double asterisk either side of the text. Examples: TapDelay1, delayTime
• Integra script should be formatted as code, by either placing a single back tick either side of the text `like this` or by indenting the code by 4 spaces per line. Examples: integra.set(“TapDelay1”, “delayTime”, .5)
• don't go any deeper than h4, i.e. ####

We recommend that you use your favourite text editor along with the Marked preview tool to write your docs.

Documentation intended for the website should be added to the project repository under documentation/trunk and can then be included in the Software/tutorials section on the website.

A good guide to written style can be found here.

Module Documentation Guidelines

• Favour simple non-technical language, e.g. use "level" instead of "amplitude"
• Keep documentation as short as possible
• Be consistent
• Phrase module descriptions as actions describing what the user uses the module for, e.g. "Granulate the audio input with a resonance applied to grains"
• Phrase endpoint descriptions as actions describing what the user uses the endpoint for, e.g. "Set the level of the fourth partial"
• No full stop the end of sentences
• Always spell units out in full with abbreviated units in parentheses, e.g. Hertz (Hz)
• Use hyphenated names for filters, e.g. low-pass, high-pass
• Start sentences with a verb, active voice, e.g. "Set", "Display", "Control", "Alter"
• Start descriptions with a simple single sentence. Any further details should be given after an empty line

Example:

Frequency

Set the cutoff frequency in Hertz (Hz) of the low-pass filter

This setting also controls the centre frequency of the resonant peak. Further information about resonant filters can be found in this Wikipedia entry