General Documentation

[musicus]

Rather than only relying on the generated documentation only, we should also use the Wiki feature here to create a manual that: (1) provides a 10 minute introductory tutorial; (2) concisely describes how to use the vis-framework; (3) how to create workflows; (4) how to achieve certain analytical goals; and (5) how to contribute to the vis-framework codebase.

There are also 14 other documentation issues we should review: #379 #343 #319 #295 #291 #287 #284 #282 #266 #256 #255 #248 #246 #195 .

[crantila]

Is there a reason not to consolidate all the documentation in the generated API?

[crantila]

That sounds like a good reason to write additional documentation, but where to write it seems irrelevant unless I'm missing something. One of the things I find most annoying about learning a new library is figuring out how to read the documentation, and putting tutorial-style material on a different website than the technical material is just one more thing to learn.

[crantila]

True, but, usually the audience for technical documentation, i.e. framework developer, is different than the audience for the end user, i.e. music theorist python hacker.

These should be the same. All of the documentation should be accessible to and useful for the music theorist. Additional documentation only relevant to Framework developers belongs in source code comments. I don't claim that I found the right balance, but it is what I tried to do.

We could put tutorial documentation into the generated API, but again that comes at the cost of further weighing down, and cluttering up the vis-framework. The framework should be as lean as possible.

Please stop using this "lean as possible" justification. It's easy to get people on board with unnecessary work when you use cool buzzwords, but where's the problem that needs to be solved? What burden is the API documentation creating?

Production environments should be installed from PyPI, which doesn't include the API, so that's 0 KiB there. Super lightweight!

People who download the repository, they're who need the API documentation, and it consumes just under 175 KiB on my computer, including the logo images and sample graph. This GitHub webpage is almost ten times the size of VIS's API (about 1400 KiB).

In either case, more documentation is always be better.

That's not true. Confusing documentation, out-of-date documentation, hard-to-find documentation, can't-remember-which-site-it's-on documentation, these are all worse than less documentation. Even music21, which has a very comprehensive set of tutorials, keeps everything in one place: the generated API documentation.

I opposed the wiki pages in the first place, because they're something else to keep up to date, and I knew it wouldn't happen. Now it's 2016, the API tutorials are out-of-date, and the wiki hasn't been touched since its creation in 2013. We haven't been able to keep even one set of docs up to date, so I just can't imagine it's a good idea to add to the maintenance burden by spreading things out.