Improve table of contents in Salt documentation #10526

Closed
JensRantil opened this Issue Feb 18, 2014 · 10 comments

Projects

None yet

4 participants

@JensRantil
Contributor

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:

  • Chapter ordering.
  • Chapters that can be merged into existing chapters.
  • Chapter sections that can be moved to a better place.

Working with this ticket will definitely benefit #9912, but I do think they are somewhat different.

@JensRantil
Contributor

I have more notes to convert into issues and will continue hopefully tomorrow night.

@whiteinge
Member

Very good suggestions here. Thanks for writing it all down!

@whiteinge whiteinge added this to the Approved for future release milestone Feb 18, 2014
@JensRantil
Contributor

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.

@whiteinge
Member

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.

@JensRantil
Contributor

@whiteinge Aight. Will do.

@whiteinge @cachedout @cro Please comment on any of these issues if you disagree with any of them.

@holmboe
Contributor
holmboe commented Feb 24, 2014

@JensRantil kudos for doing this!

@whiteinge
Member

A first step thanks to @cachedout: #10792.

@whiteinge
Member

Oh, and the result.

@JensRantil
Contributor

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!

@JensRantil JensRantil closed this Feb 26, 2014
@cachedout
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment