Better workflow for editing docs
-
So one of the key takeaways of the first HISE meetup was that there should be less friction for people that want to contribute to the HISE documentation, which is sometimes
- sparse and
- written too complicated
We talked about ways of solving this and somehow settled on me trying to explain to anybody that is interested how to use the delicate but super convoluted setup that merges autogenerated parts with custom docs to the content you see on the docs website.
BUT
that's nonsense. So instead I've added links to directly edit the file on the GitHub documentations to:
- Every site's footer (on the HTML version and the doc window inside HISE)
- Every undocumented API method in the Scripting API
For the second thing to work I had to autocreate all files for the methods, but now it should create this flow of thoughts in your head everytime you try to use the docs.
- "Let me see what this function does"
- "Good. A one liner explanation. Would be great if someone adds more context"
- "Wait, I can add more context."
- Smash that edit button, hack away into the online markdown editor, commit the change or create a pull request. If you're not sure if the explanation you wrote in there is 100% correct, don't worry as I will proof read every pull request before merging.
- The next user will thank you.
There are still a few pages which do not have a markdown file yet, but if you find one, let me know then I'll run the autogenerator again for this category.
-
@Christoph-Hart - All the docs that say, "Just ask @d-healey" are me. (And the one that says, "First!") I'm helping.
-
@Christoph-Hart Ok great, now how do I create whole new pages? for example a definition of what the tempofactor values are in "normal" and extended tempo set ups?
-
@Christoph-Hart Nice. Some still missing are Engine.createBroadcaster, Engine.addModuleStateToUserPreset, BeatportManager.validate, most of the Array class... That's just what I've seen on a very quick skim.
-
@aaronventure said in Better workflow for editing docs:
Some still missing are Engine.createBroadcaster, Engine.addModuleStateToUserPreset,
Haha that's a misunderstanding: I've deliberately omitted the link for docs that have already a description, it just shows the link for undocumented methods. The main goal is to fill up the blanks and nudge everyone towards that goal :)
-
@Christoph-Hart said in Better workflow for editing docs:
There are still a few pages which do not have a markdown file yet, but if you find one, let me know then I'll run the autogenerator again for this category.
The scriptnode's clone node has a markdown page but not the other clone-related nodes:
container.clone_forward
container.clone_cable
container.clone_pack
