search

JuliaMusic / JuliaMusic_documentation.jl

Documentation repository for JuliaMusic, built with Julia, Documenter.jl.
https://juliamusic.github.io/JuliaMusic_documentation.jl/latest/
9 stars 7 forks source link

Moving each package's documentation to respective repository #5

Closed aminya closed 4 years ago

aminya commented 4 years ago

I want to suggest moving each package's documentation to respective repositories, and optionally link all of them together to a union site (like JuliaRobotics)

Pros of this approach:

Datseris commented 4 years ago

Sorry, I don't agree with this and most of your arguments don't seem sound to me. What we could do is rename the repo, if you feel that it does missjustice to other packages of the organization. That seems totally fair for me.

At the moment, only 3 packages in JuliaMusic are in the same documentation repo, and there is very good reason for that. It makes literally no sense, and would make the life of everyone much harder, if the documentation of quantize and Note were in different websites. I wonder how you can even consider that having them in separate websites would be "easier" or "better". Documenter's entire functionality works by having everything in one website. You can't link Notes in the documentation string of quantize if they are in different websites.

I just checked the website of Julia robotics that you cited, and the very first link I've clicked was broken. Having 100s of links to other websites is hard to maintain apparently, while Documenter does the linking automatically, alleviating the need for maintaining every link.

Also, I just checked the MusicXML documentation. I noticed that many of your documentation strings have wrong layout-ing, see e.g. https://juliamusic.github.io/MusicXML.jl/dev/#MusicXML.Note . This would never happen if this documentation was part of the "JuliaMusic" documentation because:

  1. I would review the documentation myself, and 2 pairs of eyes are strictly superior to 1 pair of eyes.
  2. Having such an "organization documentation" simply enforces a higher level of quality, which the joining package must abide.

For me the popularity of this documentation I curate is meaningless, and I don't care to get more packages in here so that it is more visible. But this is a hobby I am extremely passionate about, and I would accept nothing but the highest possible quality. Sacrificing even a sliver of quality for "doing something faster" is unthinkable for me. If you also share this passion for the highest quality of software about music, I invite you to think about joining this effort, instead of stopping it.

Let's take the arguments one by one:

Make it easier to write documentation for separate packages. Different developers can write a doc without knowing all the other packages.

You present this as a statement of fact yet I don't see it at all. The only knowledge necessary is Documenter. The theme of the JuliaMusic documentation is that it explains the packages of JuliaMusic. It doesn't enforce you to learn all of them...

Make it easier for the user to understand the API of each package. Instead of having all of them spread on a single website.

This also doesn't stand. You don't have to read the entire documentation, since if e.g. MusicXML was part of this, there would be a very clear section on the left with the title "MusicXML".

Many packages and Julia itself have the documentation in the same repository

Okay... why is this an argument? To counter-example: DynamicalSystems.jl, DifferentialEquations.jl, the actual Julia language, and others, are examples where things work exactly as in here. (Would you ask the Julia language to move the FIlePath module documentation to another website?)

This repository can be simplified or removed.

I don't see why this is an argument either... 100% of the lines of code in this repository are absolutely necessary, as 100% of them are useful documentation. If this repository did not exist, these lines would in fact increase in size instead of decrease, as a lot of boilerplate and cross linking would be added. Seems to me that removing this repository is a downside, not a benefit.

Enables a simpler approach for automatic doc creation using Github Actions or Travis CI

Didn't understand this either. The documentation of this repo is built automatically on travis as well...

New packages can be added without moving their documentation to this repo. For example, currently, MusicXML.jl has its own doc. In the near future, other packages will be added (e.g. Fretboards.jl). It will be a mess to move all of them here. Also, this repo may be misleading, as it doesn't include the doc for everything.

This is a valid argument. Notice that new packages are being added, there is no constrain and they have nothing to do with this repo. You already have added MusicXML which has its on docs. But, I clearly see and accept your argument that the name is misleading, and I am very happy to accept to change it to something more appropriate. At the moment I can't think of something, feel free to open a new issue with suggestions about better name.

So, let me mention some downsides of having all documentation in one repo, as I see them from my perspective (and experience with doing this for other organizations as well):

  1. One can't add the documentation of a new feature in the PR of that new feature, as the docs PR and the feature PR happen in different packages.
  2. One has to wait for a version of a package to be tagged first before using the new features in this documentation here.

For me it is well worth the price to have a unified docs, as the benefits vastly outweigh these things.

aminya commented 4 years ago

For me the popularity of this documentation I curate is meaningless, and I don't care to get more packages in here so that it is more visible. But this is a hobby I am extremely passionate about, and I would accept nothing but the highest possible quality. Sacrificing even a sliver of quality for "doing something faster" is unthinkable for me. If you also share this passion for the highest quality of software about music, I invite you to think about joining this effort, instead of stopping it.

I don't want to make this simple request like a drama.

This is just a simple request.

If I want to use quantize I should know which package I should load. Is it MIDI or MusicManipulations? That's what I mean by separating docs. What if I want to study the API of MusicManipulations only. How can I do that?

I can make a PR to Documenter to allow cross-referencing from different packages, but that is not a good enough reason not to do it

This also doesn't stand. You don't have to read the entire documentation, since if e.g. MusicXML was part of this, there would be a very clear section on the left with the title "MusicXML".

I don't see why this is an argument either... 100% of the lines of code in this repository are absolutely necessary, as 100% of them are useful documentation. If this repository did not exist, these lines would in fact increase in size instead of decrease, as a lot of boilerplate and cross linking would be added. Seems to me that removing this repository is a downside, not a benefit.

By this I meant, this repo can be used as a unified website to give links to the documentation of each package.

Regarding the name, I recommend "MIDIMusicManipulations...." (basically the name of all packages living there.)

Anyways, I think we need to get ideas from others too. It's not just you and me deciding about this. The idea of other developers as well as the users is also important.

Datseris commented 4 years ago

If I want to use quantize I should know which package I should load. Is it MIDI or MusicManipulations? That's what I mean by separating docs.

...? All documentation strings generated by documenter have their parent module as prefix. You don't see quantize, you see MusicManipulations.quantize. https://juliamusic.github.io/JuliaMusic_documentation.jl/latest/mm/quantizing/#MusicManipulations.quantize3

What if I want to study the API of MusicManipulations only. How can I do that?

This is exactly the reason MusicManipulations has a documentation that is bundled with MIDI. Because it doesn't make sense to "study its API" without knowing the MIDI api. It directly expands on the MIDI api, and in fact I don't think it is sensible to consider them having a different API.

To give an example: it doesn't make sense to study the iteration API of Base.iterate without knowing the API of a for loop. This is why they are at the same website. Imagine for a moment asking to move the Base.iterate API to a website different from the for loop. This is how your request sounds to me.

We need to be clear about some things before continuing this discussion. How much have you read and used the packages that are documented in this JuliaMusic website? Because it is crucial that this discussion is done between people that have a good idea about most of this documentation.

By this I meant, this repo can be used as a unified website to give links to the documentation of each package.

Sure, I can link the other packages there. But I also see the option of just putting MusicXML there, as it would only be one additional entry on the sidebar column, e.g. after "Data extraction" https://juliamusic.github.io/JuliaMusic_documentation.jl/latest/

Anyways, I think we need to get ideas from others too. It's not just you and me deciding about this. The idea of other developers as well as the users is also important.

Well yes and no. Many people have already read and used this documentation, even for doing science. I don't have much doubt that the way it is right now is helpful to the people using it. What I need to change it is convincing arguments.

Can you give any argument that having the documentation of e.g. quantize and Note in different websites is "better" than having them together? If you can't provide any such argument, it doesn't make sense to argue for splitting their documentations.

Again, if your goal is to have more fairness for other packages (which is exactly what my comment about not caring about visibility was about and not about "Drama"), feel free to suggest a better name.

Regarding the name, I recommend "MIDIMusicManipulations...." (basically the name of all packages living there.)

Does this sound like a good name to you? Because in all honesty having the title of a page to be MIDI_MusicManipulations_MusicVisualizations sounds terrible to me.