search

ambisonictoolkit / ambisonictoolkit.github.io

Website - using Jekyll and Bootstrap
GNU Lesser General Public License v3.0
12 stars 4 forks source link

Add documentation to the atk-reaper plugins #20

Open mtmccrea opened 8 years ago

mtmccrea commented 8 years ago

Aside from Jo and Trond's paper, there isn't specific documentation for individual plugins.

What form this would take is open, but for the near-term, one possibility is to make each plugin listed on the left column of the atk-reaper page into a link pointing to it's SC counterpart in SCDocs would provide more information. For example Encoders>Mono Signals>Diffuse would link to *newDiffuse.

Taking the long view, something with in-depth descriptions, notes, warnings, suggestions, etc, and screenshots would be very useful. Something between a "manual" and what's found in TOA's "plugin list" tabs in each plugin suite.

joslloand commented 8 years ago

This sounds sensible. The short term view of linking to SCDocs is really just a stop gap. We'd want to mention this so that users don't become too confused.

I think the long view does make sense. Of course, more work, but could easily be modeled on the text already in SCDocs.

lossius commented 8 years ago

IMHO screencasts is the way to go. No one read manuals any longer, but screencasts are watched a lot. As an example, the "encoding mono" screencast already has 59 views, in less than two days.

joslloand commented 8 years ago

I had imagined that we might write some web pages along the lines of Blue Ripple's Manuals. These obviously take some time to put together.

The advantage is that a written text can quickly be searched and updated with technical information as need be.

The disadvantage is finding the time to prepare.

For atk-sc3 the goal is always to document via SC3's help system, as that makes a complete package....

mtmccrea commented 8 years ago

Relatedly, being able to index the contents and have anchors is useful when wanting to jump to particular sections. This could be useful for the videos if it's possible to have "jump-to" links in Vimeo videos as you can with YouTube.

Great work on the videos, Trond!

On Wed, Sep 14, 2016 at 12:17 PM, Joseph Anderson notifications@github.com wrote:

I had imagined that we might write some web pages along the lines of Blue Ripple's Manuals http://www.blueripplesound.com/manuals. These obviously take some time to put together.

The advantage is that a written text can quickly be searched and updated with technical information as need be.

The disadvantage is finding the time to prepare.

For atk-sc3 the goal is always to document via SC3's help system, as that makes a complete package....

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/ambisonictoolkit/ambisonictoolkit.github.io/issues/20#issuecomment-247123902, or mute the thread https://github.com/notifications/unsubscribe-auth/AA4WzgIwUTAu3RBO1_wqvG4d7qfu2JzIks5qqEhYgaJpZM4Iwant .

lossius commented 8 years ago

I feel that we need to be realistic about how much resources we have available for this. For me it is very low priority to write manuals, even though they can be easily versioned in the future. To be honest I doubt that I will ever manage to muster the inspiration to do so...

Manuals really are kind of old-fashioned now. Interactive documentation within the program as is the case with sc3 is fine, but hardly no-one makes use of HTML or PDF documentation any more.