I've spent some time for the past two weeks reading the Salt documentation. I'm a beginner at Salt and saw this as an opportunity to give some feedback on the documentation from some fresh eyes perspective. I've made notes of possible improvements along the way and will file separate issues referring to this one. See this issue as a general discussion place for disposition improvements and feel free to close it if you find too unspecific or unsolvable.
Last week I was mostly reading the web version of the documentation. The past five days I've been reading the latest version of the PDF.
Something that has struck med over the past few days, mostly when reading the PDF, is that the disposition of the manual could be hugely improved. Currently there are 120(!) chapters in the documentation which makes it very hard to find what you are looking for in the table of contents. I understand the Salt project has many tools, but it's not a 120-chapter-project (yet) 😄. I personally find a well structure TOC/index crucial for a documentation to be very usable.
Here are some things that I've been thinking about:
Working with this ticket will definitely benefit #9912, but I do think they are somewhat different.
I have more notes to convert into issues and will continue hopefully tomorrow night.
Very good suggestions here. Thanks for writing it all down!
So far these are all the notes I've made. I'll create more issues if I find more things to comment/improve on.
Most things are relatively easy to fix (and beginner friendly). I don't currently have a computer at hand, but could possibly have a look at some these things when I get back from vacation.
Please do! When you dive in, please drop an update comment here or jump on IRC to hit up myself or cachedout or cro so we can coordinate and not duplicate efforts. Thanks again for the great feedback.
@whiteinge Aight. Will do.
@whiteinge @cachedout @cro Please comment on any of these issues if you disagree with any of them.
@JensRantil kudos for doing this!
A first step thanks to @cachedout: #10792.
Oh, and the result.
Great work, @cachedout! I could close all issues except one. In fact, I am closing this one too as I find the TOC so much more enjoyable. Once again, great work!
Thanks, @JensRantil ! I'm so glad you like these changes. Thanks for the kind words. The issues you filed were instrumental in figuring out how to re-organize the docs.