saltstack / saltstack/salt

[DOCS] Improvements to core Salt doc topics requested by VMware customers

Open
#64,473 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation severity-high time-estimate-sprint VMware
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

The VMware customer support team requested some improvements to core Salt documentation that is causing a lot of confusion with VMware customers. They wanted a Salt engineer to review a few of these docs to let us know which elements are out of date, contain missing information, or that are wrong:

  • Troubleshooting the Salt Master
    • We just need a quick pass on this to validate that the content is still accurate.
    • To give an example of something that we think is maybe outdated or no longer necessary, the section about too many files is still a concern but not as important as a concern as it used to be.
  • High availability features in Salt
    • This could be good for a general review.
    • One thing is that we probably just need to add that minions actually send events back to all masters now. This is relatively new functionality and it needs to be called out specifically since it appears to be undocumented.
  • Using Salt at scale
    • This also just needs a general review for validation.
    • For example, there are recommended configuration options related to SOC that might be irrelevant.

After a Salt engineer did a review, he made these recommendations:

  • For Troubleshooting The Salt Master I think the entire "Too Many Files" section can get axed. I also think the section below it "Master Stops Responding" can get axed. Especially if other team members agree they can go away.
  • The high availability features of salt section is okay for now. As far as events getting sent to both masters, That might be a bug, not a feature or if it is a feature it's one I'm not aware of. The rest of that doc looks accurate to me.
  • Scaling doc looks okay but I'm sure it can be improved. I think we'll have some more options on both those in a future release.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the three linked Salt documentation topics: topics/troubleshooting/master.html, topics/highavailability/index.html, and topics/tutorials/intro_scale.html. Compare each section with current Salt behavior and resolve the listed concerns; done means outdated or incorrect guidance is identified and the agreed documentation updates are clearly recorded.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.