Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

General Documentation #380

Closed
musicus opened this issue Apr 1, 2016 · 3 comments
Closed

General Documentation #380

musicus opened this issue Apr 1, 2016 · 3 comments

Comments

@musicus
Copy link
Contributor

musicus commented Apr 1, 2016

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 .

@musicus musicus self-assigned this Apr 1, 2016
@musicus musicus added this to the Release 3.0 milestone Apr 1, 2016
@crantila
Copy link
Member

crantila commented Apr 4, 2016

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

@crantila
Copy link
Member

crantila commented Apr 4, 2016

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.

@musicus musicus mentioned this issue Apr 4, 2016
@crantila
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants