New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve table of contents in Salt documentation #10526

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

Comments

Projects
None yet
4 participants
@JensRantil
Contributor

JensRantil commented Feb 18, 2014

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

This comment has been minimized.

Show comment
Hide comment
@JensRantil

JensRantil Feb 18, 2014

Contributor

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

Contributor

JensRantil commented Feb 18, 2014

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

@whiteinge

This comment has been minimized.

Show comment
Hide comment
@whiteinge

whiteinge Feb 18, 2014

Contributor

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

Contributor

whiteinge commented Feb 18, 2014

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

@JensRantil

This comment has been minimized.

Show comment
Hide comment
@JensRantil

JensRantil Feb 18, 2014

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.

Contributor

JensRantil commented Feb 18, 2014

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

This comment has been minimized.

Show comment
Hide comment
@whiteinge

whiteinge Feb 18, 2014

Contributor

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.

Contributor

whiteinge commented Feb 18, 2014

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

This comment has been minimized.

Show comment
Hide comment
@JensRantil

JensRantil Feb 19, 2014

Contributor

@whiteinge Aight. Will do.

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

Contributor

JensRantil commented Feb 19, 2014

@whiteinge Aight. Will do.

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

@holmboe

This comment has been minimized.

Show comment
Hide comment
@holmboe

holmboe Feb 24, 2014

Contributor

@JensRantil kudos for doing this!

Contributor

holmboe commented Feb 24, 2014

@JensRantil kudos for doing this!

@whiteinge

This comment has been minimized.

Show comment
Hide comment
@whiteinge

whiteinge Feb 26, 2014

Contributor

A first step thanks to @cachedout: #10792.

Contributor

whiteinge commented Feb 26, 2014

A first step thanks to @cachedout: #10792.

@whiteinge

This comment has been minimized.

Show comment
Hide comment
@whiteinge

whiteinge Feb 26, 2014

Contributor

Oh, and the result.

Contributor

whiteinge commented Feb 26, 2014

Oh, and the result.

@JensRantil

This comment has been minimized.

Show comment
Hide comment
@JensRantil

JensRantil Feb 26, 2014

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!

Contributor

JensRantil commented Feb 26, 2014

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

This comment has been minimized.

Show comment
Hide comment
@cachedout

cachedout Feb 26, 2014

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.

Contributor

cachedout commented Feb 26, 2014

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