Pulled in the documentation into the site

[abhi18av]

Hi @daveyarwood

I thought that I could contribute with the website so I just pulled in all the documentation pages from the former main Alda repo.

Also there are three stubborn files which are refusing to be converted into html

• rests
• markers
• offset

I've tried a lot to convert them but now i'm out of my wits:)

The pages to need some finishing up - I thought it's best to ask your feedback prior to doing any more work here.

[daveyarwood]

This is an interesting idea, moving the docs from the alda-lang/alda repo to the website. I'm not necessarily opposed to doing it this way, but I'll have to think about this a bit. One potential advantage is that our docs would be available at an easy-to-remember URL as part of the Alda site, and could be displayed in a friendlier format than GitHub offers; currently browsing our docs feels more like browsing files in a repository than reading documentation on a website.

I'll take a closer look at this soon. Thanks for the PR!

[daveyarwood]

/docs would be a better route name in my opinion

[abhi18av]

The ideal solution would be to have replace the documentation.md to something like docs.md which translates to a ./docs/ folder that contains all the docs. But, I'm not that experienced with Jekyll so doing that would need a bit more calibration, I couldn't figure out the paths much myself.

[abhi18av]

@daveyarwood yes, because I thought since the target users include Non-tech people as well - why not make an effort to make the first steps more user friendly :)

[daveyarwood]

Revisiting my thoughts in #1:

Some small amount of documentation? I think that GitHub is the best place to keep Alda's documentation, as we manage it in version control along with the source code. It occurred to me that we could have nicer looking documentation on alda.io, but I think it might be better to have a "Quick Start" page on alda.io just to give visitors a basic idea of how to use it. This page would link to the official docs in the GitHub repo for more in-depth documentation.

Thinking about this more, I think I still mostly feel the same way about Alda's documentation (but see below). I think that being able to manage the docs in version control alongside the source code is very important, so GitHub is probably still the best place for all of the technical details. That being said, I do think it would be nice to have the most useful information available as a sort of "Quick Start" guide on the alda.io website, and we could link to the GitHub repo docs for more detailed information, at least for now.

I think the real issue, though, is that our docs in GitHub are not organized well enough to be suitable documentation to be displayed in website form, and the docs need to be fundamentally rewritten before we can include them prominently on alda.io.

Looking at the docs for other programming languages (e.g. Python), I'm starting to get some ideas of how to organize things better. I'll create a new issue for this effort, and leave some notes there.

@abhi18av I appreciate this PR, even though I can't merge it -- it is at least making me think more critically about our documentation. :)

[abhi18av]

No issues @daveyarwood 😄

I'm happy to help anyhow.