Improve Alda language documentation

[daveyarwood]

Continuing the conversation from #1 / #7 (cc: @abhi18av):

Alda's documentation currently lives as a series of unorganized Markdown files in the main Alda repo. My initial thought was that the documentation could be managed in version control alongside the source code, which is compelling.

However, I think it's more important to have helpful, well-organized documentation available on alda.io, with more of a focus on making it easier to find the information you're looking for.

I think the Python documentation is a good source of inspiration. There are some nice features here:

• The documentation is available by release version. For example, if you're using Python 3.5 instead of 3.6, you can find the latest 3.5 version (i.e. 3.5.3) docs here.

• The landing page has big links to the most relevant information, like the changelog, a tutorial, installation instructions, an FAQ, etc.

• As you navigate through the docs, there is a sidebar with quick links to each section, making it easy to zero in on a particular section.

I previously looked into http://readthedocs.io, and it seems like a nice way to set up something like this. I did a quick port of our existing documentation here: http://alda.readthedocs.io/en/latest/

The docs are actually generated from the alda-lang/alda repo, which is great because we can still keep the docs version controlled alongside the source code, and easily generate different versions of the documentation based on Alda release versions.

The next steps are to organize the docs better so that they look good on readthedocs.io, and then we could CNAME the docs to something like http://docs.alda.io and include a link on the website.

[abhi18av]

@daveyarwood This looks great to me!

I've actually been a huge fan of python community's documenting tools, so this is promising. But could you please elaborate more on what the changes you'd like to see in the content?

You mentioned reworking the docs, might I suggest doing it thematically - as in, pick some actual sheet music and then transcribe it bit by bit. Start with the reader as a musician and then slowly lead one to the programmable music aspects of Alda.

Oh, I'm working on a tutorial, based on this Music Theory for Normal People - Toby Rush. The author has organised the material in a nice narrative.

If you could put up your ideas and vision than this can work quite well.

[daveyarwood]

You mentioned reworking the docs, might I suggest doing it thematically - as in, pick some actual sheet music and then transcribe it bit by bit. Start with the reader as a musician and then slowly lead one to the programmable music aspects of Alda.

I like this idea a lot. I think this would work well as part of a multi-step tutorial to the Alda language that would live in the documentation. Perhaps the first couple pages could be inspired by (or maybe even pulled directly from) this introductory blog post I wrote a while back, just as a quick introduction to the syntax, and then the next part of the tutorial could walk the reader through transcribing a snippet of sheet music in Alda.

I've actually been a huge fan of python community's documenting tools, so this is promising. But could you please elaborate more on what the changes you'd like to see in the content?

The docs we have now are lacking two things:

• a directional narrative -- I always enjoy reading documentation that can be read and explored from top to bottom. Right now, we have a variety of documents that all refer to each other, and it isn't exactly clear where to start and where to go after reading about each concept.

  It would be great if there were a clear starting point from the landing page of Alda's docs, so you could start there and by guided through in a way that feels like you're learning the language from start to finish.

• an organizational hierarchy -- we currently have a variety of information collected in a single folder of Markdown documents. What I think would be more useful is if we had a handful of useful sections, like Setup, Reference, Tutorial, What's New? etc. similar to the landing page of the Python documentation.

---

I made a quick sketch of what these sections might look like:

From the landing page, sections could include:

• What's new in Alda 1.0.0? (1.1.0, 1.2.0, etc.)
• Setup and Usage
• Tutorial (see below)
• Reference (would include things like...)
  • list of instruments
  • list of attributes
  • alda.lisp API docs (i.e. a list of functions available in the alda.lisp namespace, what they do and how to use them)
• The Alda Command-Line Client
• Developer Portal (would include information like...)
  • Using Alda in a Clojure program
  • Technical details about Alda components
  • Writing your own Alda components
  • ZeroMQ architecture
• Community (links to the Alda Slack group, subreddit, GitHub org, etc. and information about contributing to Alda)

The tutorial sections could be something like:

• Anatomy of an Alda Score (a broad overview of the structure of a score file, explaining instrument parts, variable definitions, etc. without going into too much detail)
• Notes and Rests
• Chords and Voices
• Grouping Instruments (covers instrument groups and naming instruments/groups)
• Attributes
• Advanced Rhythms (covers second/millisecond durations and CRAM notation)
• Using Variables
• Generating Music by Writing Code (covers inline Clojure code and an overview of the alda.lisp DSL)

This is just a quick sketch; I'm definitely open to any suggestions about how to tweak this, but maybe this outline can be a good starting point.

[abhi18av]

@daveyarwood Let's include the your talk videos in the docs.

Alda: A Music Programming Language, Built in Clojure (David Yarwood)

Alda: A text based music composition language

And a few links to people who aren't as familiar with music theory at all, like Open Music Theory in addition to the one I mentioned above.

I feel that in the docs we just kinda assume that people who're coming in are proficient in the notations and we pick up from there - but, let's offer a few links for learning resources.

[daveyarwood]

That's a good idea. I'm not sure exactly where the video links should go -- maybe we could have another top-level section called Talks & Demos, or something like that?

I agree it's also a good idea to include some resources for learning music theory / how to read sheet music in the docs. I'm sure there are a lot of people who want to learn how to read and write music, and are interested in learning Alda as a way to help them do that.

[abhi18av]

Yup, this looks good, videos go a long way as compared to text.

• Also I feel we need to expand on the examples to something more like a gallery.
• We need to update the build instructions for the new organization as well.

@daveyarwood Shall we create todo/issues/project about what we've decided here.

[daveyarwood]

Sure -- I'll divide this up into smaller issues so the effort is easier to manage.

[daveyarwood]

I think an Alda cheat sheet ( #3 ) would also be a nice link to include in the documentation.

[daveyarwood]

I've broken this issue up into a bunch of smaller issues -- closing this one.

(although, if anybody has any additional comments that don't fit in any of the issues referenced above, feel free to leave them here)