improving documentation usability 

Drawing on my experiences as a new user, and further discussions with new and power users, as well as with the lead developer (Michael E.), we have reached a consensus on how to re-organize the documentation for improving usability.

There are two main points to be noted:

  • move some or all existing (non-interactive) documentation to a wiki
  • ‘atomize’ documentation of all functions, and illustrate each with a limited collection of simplified examples that are re-used across entries (in the spirit of ‘hello world’).

The atomization will allow for functions and techniques to be more easily learned, as well as more effectively communicating how to combine them to achieve desired results.

The role of traditional wiki ‘discussion’ (aka ‘talk’, ‘sandbox’, etc.) pages could be served by the current microblog (where this entry was originally posted). The microblog has already been earmarked as a target destination to which existing social media discussions of the software will be migrated.

Over time, a two-way relationship can evolve between the microblog and wiki, where questions can be answered by microblog links to the wiki, and solutions arrived at in microblog discussions can be added to the wiki when an entry is absent or missing details (including a link back to the original microblog discussion).

A further benefit of using a wiki is its internal network structure, where each entry is a node (aka ‘deep link’) that can be linked to any other entry, allowing for the expansion of explanations as needed by a given user (e.g. an entry on mapping pitches to rhythms might link to an entry on specifying pitches; an entry on specifying basic rhythms might link to an entry on adding more detailed articulations such as accents, etc.).

Lastly, the use of tags in a wiki would allow for multiple concurrent organisations of concepts. To illustrate why this would be useful, consider that the way dynamics are implemented in a single bar differs from how they are implemented in multi-bar structures. A hierarchically organised wiki structure with tags would allow for a user to approach the documentation in two different ways: a user could choose to focus on the group of all operations involving dynamics in one or more bars, or, alternatively, on all operations that can be performed on a single bar and/or those that can be performed across multiple bars.