-
Notifications
You must be signed in to change notification settings - Fork 7
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
Moving each package's documentation to respective repository #5
Comments
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 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:
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:
You present this as a statement of fact yet I don't see it at all. The only knowledge necessary is
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".
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
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.
Didn't understand this either. The documentation of this repo is built automatically on travis as well...
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):
For me it is well worth the price to have a unified docs, as the benefits vastly outweigh these things. |
I don't want to make this simple request like a drama. This is just a simple request. If I want to use 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
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 "MIDI_MusicManipulations_...." (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. |
...? All documentation strings generated by documenter have their parent module as prefix. You don't see
This is exactly the reason To give an example: it doesn't make sense to study the iteration API of 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.
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/
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. 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.
Does this sound like a good name to you? Because in all honesty having the title of a page to be |
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:
The text was updated successfully, but these errors were encountered: