Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
There are two types of documentation used in the Integra project: written documentation and screencasts. All documentation should be clear, concise and focused.
- 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.
- 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. ####
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
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