This is the SaltStack Documentation Working Group repository. For other working groups, checkout the SaltStack Community repository.

Documentation Working Group

The purpose of the Documentation Working Group is to improve the overall quality of Salt documentation by:

• Decreasing the time investment for new users to onboard
• Scaling the docs for various user skill levels, beginning to advanced
• Optimizing navigation for speed and relevance
• Enhancing real world applicability by adding tutorials and clear use-case scenarios
• Providing clear indicators of module maturity and stability in related documentation

WORKING GROUP CONTRIBUTION GUIDELINES

Guidelines for contributing to (and communicating with) this working group:

• It is not required to be a member to assist the group's goal achievement
  • However, only members may advocate for solutions
  • Action is emphasized throughout the lifecycle and not simply planning and deliberation
• Please complete task commitments
  • Do not over commit to task beyond your means
• Ask for help and communicate to avoid developing in a vacuum
  • We encourage asking for help from other members and from the salt community, at large.
• Put good faith effort into resolving issues with the current toolset before requesting to add/replace a tool.
  • No one is to add a tool without deliberation and consent.

WORKING GROUP DETAILS AND TOOLS

Meeting details

Meetings will take place every other Thursday at 2p.m. Mountain Time/3p.m. Central Time. Check the Salt Community Calendar (ICS) for the Zoom link.

Group Tools

• Slack: #documentation channel at Slack
• Additional tools are yet to be determined among the group captain and members

Project task structure

• Single day tasks (labeled SSD solo single day task)
  • Page fix/adjustment/404 link error
  • Reducing a page’s complexity
• Individual long term projects (labeled SLT solo long term task)
  • How-to documentation
  • New page or section i.e. new feature
  • Consolidating pages
• Multi-persons projects (labeled multiple tasks)
  • Code/tool migration
  • Creating new repositories/application for docs.saltproject.io

WHY JOIN?

Improving open source documentation has a big impact

Good documentation helps orient newcomers, improves the project’s overall usability, and ensures that the community continues to grow. Even small contributions make a big difference.

Users at any skill level can contribute

If you are new to Salt and want to contribute as a community member, the Documentation Working Group is one of the best groups to join because it has a low barrier to entry for contribution. You will get more familiar with Salt and what it is like to contribute while working on a low-stress project appreciated by the entire community. If you are a seasoned user, your expertise is valuable because you have a better sense of what users expect when reading software documentation. All contributions are welcome!

Documentation makes a difference

In 2017, GitHub conducted the Open Source Survey, sampling 5,500 respondents. One key takeaway was “documentation is highly valued, but often overlooked.” The survey found outdated or confusing documentation to be a major problem, affecting 93% of respondents. Yet 60% of contributors rarely or never contribute to documentation. Consider giving back to the community by helping improve the docs.