Ansible docs sprawl
infovore opened this issue · comments
The Ansible documentation is getting really long.
This thread on lines is in part about a perceived issue that came down to
- a change in default behaviour after a firmware update
- ...that they couldn't find an explanation of how to alter in the documentation
- ...despite it actually being documented.
Ansible now has... five apps, MIDI support, Teletype docs, USB disk mode docs, and further notes. This is a lot for one page, and the monome site's design means that headers aren't super-varied in their styling (despite header levels being well-used in the docs).
I propose that we break up Ansible into an 'index' page (with brief descriptions of the apps, and some global notes) as well as individual documentation pages for apps. This is also a good opportunity to review the docs properly, for inaccuracies, duplication, and also for consistency in terminology.
I'm happy to take the lead on this, but want to raise it with the community.
@infovore , I just mentioned this to @tehn yesterday -- there was a Kria support request that made clear the need for some optimization. excellent timing and thank you for opening the issue!
I love the idea to split the apps into separate doc pages, which is also in line with a plan to create short video demonstrations of parameters/functions within each app.
happy to share the work if you're able, but can also totally take this on. I've already self-assigned, let me know!
I think I'd like to take a pass at this - I enjoyed working on the Ansible docs last time, and I wrote a pile of the docs for Ansible-Earthsea too. It's likely it's going to be a bit of a running branch whilst we fettle it - I don't think it's just a case of cutting it into six!
One question, which @tehn might be able to answer: is there an easy way of previewing how the docs will look in the monome site itself?
(one note: I am on vacation the next two weeks, but I might still do some prodding. but it becomes easier to work on this in October).
(might be worth kicking off a 'project' - there are some things where I'd like review etc of)
sounds great! happy to do whatever's needed, just let me know :)
https://github.com/monome/docs/projects/1
Annoyingly, it looks like I can't add tickets to a project - I wasn't quite sure how that worked on repos I'm not a collaborator on. No worries, there's not a burning issue just yet. Although I've kicked off my own branch for now and my own project, and I'll manage it there and maybe just submit PRs. We'll see.
@infovore added you as a collaborator!
there currently is not a great way to preview the monome.org docs.
but, they do look pretty similar to basically any markdown render. so you can use MacDown or something similar