Is this the agenda for the meeting or can other topics be discussed?
I would propose an extension of the release numbering to allow for documentation only releases.
The format would be X.Y.Z where currently X==3, Y==14. Z releases would be specifically and exclusively for documentation updates, i.e. schelp & tutorials.
SC is missing a lot of documentation and some of it is broken. If doc is ONLY released when new code is released the doc will never catch up. Z releases as only doc would not require testing of the code base as that will not have changed, so such releases would require less effort.
I hear people talking about āhow to get more people to use SCā and āthe future of SCā. I believe the answer to the first is more and better documentation, and for the second, everyone (not just a small group) needs to understand where SC is now, it abilities & limitations, before discussing / deciding where SC should go in the future ā again better/more documentation will help.
Who am I: software developer, many decades of experience, mostly internals of: OS, DB, VM, compiler & interpreter. I have used many PL, but the ones I got paid for are: Assembler, C, C++, Java & PERL. I have also taught programming and written technical documentation & tutorials.
I would propose an extension of the release numbering to allow for documentation only releases.
Why do we need a dedicated version scheme? Nothing is stopping us from making bug fix releases that only contain documentation improvements. Also, bug fix releases happen quite regularly anyway, so I donāt really see the issueā¦
Iāll second spacechild1 view, but Iād also favor to keep patch releases for patches and not new features/content - ideally we get into a flow of releasing a new minor version once/twice a year in order to keep releases manageable by reducing moving things, which makes the need to cram new features into patch releases obsolete.
Either way of how such doc improvements would be released, it is most important to actually make these improvement on the docs - I think we are currently on a good path to make some improvements in this department but more help is always appreciated!
Also - people who are interested in the most up-to-date docs can visit https://dev.docs.supercollider.online/ which gets build weekly from the dev branch.
I opened the following PR to help address this issue:
I fully agree with @code2musicās remarks regarding the importance of comprehensive and reliable documentation:
SC is missing a lot of documentation and some of it is broken.
ā¦
I hear people talking about āhow to get more people to use SCā and āthe future of SCā. I believe the answer to the first is more and better documentation, and for the second, everyone (not just a small group) needs to understand where SC is now, it abilities & limitations, before discussing / deciding where SC should go in the future ā again better/more documentation will help.
At the same time, I also support the perspectives shared by @Spacechild1 and @dscheiba. In my view, the most effective approach would be to incorporate the development branchās documentation into the bundled documentation home. This would provide users with clearer access to the most current resources, without disrupting the stability of the official release documentation.
added:
At times, addressing or completing documentation issues may prompt developers to rewrite a class method definition. Consequently, limiting work to documentation fixes alone would be of rather limited scope.
Since SC help browser is a web browser, there is no reason it canāt just look at a webpage. We could release docs independent from the rest of the project.
Thank you for the suggestion. While I agree that, in principle, the help browser could point to an external webpage, I believe releasing the documentation separately from the rest of the project may introduce unnecessary complexity for users.
If we were to separate the documentation, users would need to install two components:
ā¢ the documentation folder
ā¢ the executable parts of SuperCollider
Likewise, developers would need to maintain and distribute two distinct packages.
From the userās perspective, installing SuperCollider is already somewhat involved, given the number of components:
Considering this, I feel the most practical solution would be to include a link to the developer documentation directly within the SC home environment.
I moved this discussion to a new thread because the dev meeting scheduling thread should really remain just for scheduling polls only, no topic discussion.
I volunteer to help verify/fix/extend/improve the SC docs.
I agree that the most import thing is to improve the docs and how they are released is secondary, but not unimportant. I will therefore detail my thinking only this one time and then I will shut up about X.Y.Z, unless others bring this up for discussion.
Please read:
Simply put, it is a matter of clarity, control and efficiency.
If we use 3.15 for both code & doc fixes, we are still playing catch-up. Note that 3.14 broke docs that were working in 3.13.
If we use 3.15 for doc fixes only, that will delay the release of code already in development and targeted for 3.15. This will also frustrate some developers because their code was not in the 3.15 release.
If we release doc fixes in 3.14.1, after having announced a new release numbering scheme (X.Y.Z) we can clearly state: ā.Z point releases are for docs ONLY, which makes doc updates safer & faster. Code releases are in .Y releases as before, and 3.15 is still on schedule.ā
The better docs in 3.14.1 make the code in 3.14 more usable while the construction of 3.15 is in progress.
The X.Y.Z numbering scheme also says to developers āyour code is not being ignored, the next X.Y (e.g. 3.15) release is still the next code releaseā
But we can already do that! 3.14.1 would simply be a bug fix release for 3.14 and itās very likely that we will get at least one bug fix releases before 3.15.
ā.Z point releases are for docs ONLY,
SC follows semantic versioning (semver). The Z in SC X.Y.Z means ābug fixā.
I would agree here that documentation fixes are 100% appropriate for bug fix releases, and, if there is no reason to withhold documentation fixes from bug fix releases, there is also no reason to withhold bug fixes from bug fix releases.
To me this is kind of a non-question. I donāt see a need for a release that is strictly limited to documentation updates. We should strive to have more frequent bug fix releases, including doc fixes and bug fixes.
I volunteer to help verify/fix/extend/improve the SC docs.
This is greatly appreciated! If youād like to chat about the general outlook of scdoc improvement, I should hopefully have time in the coming week. Awfully busy right now with a last minute job application, so technically Iām procrastinating by writing here.
On the versioning scheme, I have almost no opinion - not enough experience with software devt on my end. I figure thereās an edge case there where there are lots of doc updates but no real code updatesā¦ but as long as one explicitly allows a bug fix to be doc only, I see no problem.
I volunteer to help verify/fix/extend/improve the SC docs.
Count me in!
Not sure if Iāll find time for a meeting next week, but Iād be happy to take over any open tasks for the job.
About documentation only release, I would agree with @jordan: we could release docs independent from the rest of the project.
In my humble opinion it might be a nice solution to let the IDE check for documentation updates on startup, pretty much like a file-sharing or cloud syncing system.
