Open sebastiancarlos opened 1 year ago
Hi there! Welcome to the Salt Community! Thank you for making your first contribution. We have a lengthy process for issues and PRs. Someone from the Core Team will follow up as soon as possible. In the meantime, here’s some information that may help as you continue your Salt journey. Please be sure to review our Code of Conduct. Also, check out some of our community resources including:
There are lots of ways to get involved in our community. Every month, there are around a dozen opportunities to meet with other contributors and the Salt Core team and collaborate in real time. The best way to keep track is by subscribing to the Salt Community Events Calendar. If you have additional questions, email us at saltproject@vmware.com. We’re glad you’ve joined our community and look forward to doing awesome things with you!
@sebastiancarlos , thanks for pointing this out.
In some of our unpublished training materials, I noticed this line:
Salt ships with a number of man pages. The default man pages are standard descriptions of how to use the individual commands that ship with Salt, but a very large man page is included:
man 7 salt
So, it looks like man 7 is the "everything but the kitchen sink" documentation. This is confirmed by a team member who told me:
I think those pages are all of the Sphinx documentation, converted into Man pages. Salt docs, in PDF form, I think were 5000+ pages, so this is likely mapped
For what it's worth, according to the unpublished training I referenced earlier, the preferred method of accessing the CLI documentation is to use the status
command. For example, to view documentation for the status execution module:
salt \*master sys.doc status
You can also view the entire list of available functions:
salt \*master sys.list_functions
You can also list all functions for a specific module:
salt \*master sys.list_functions cp
TLDR;
My take on this issue is that it sounds like an interesting project to evaluate our man page effectiveness and do some research into best practices and how to trim it down. That being said, it sounds like a time-intensive project that doesn't offer clear value to our users. For that reason, I'll keep this issue open and invite anyone in the community to work on it, they can certainly do so.
I welcome other people's takes on it, though.
Your mission, Jim, should you choose to accept it, is to find meaning in salt.7 and trim it down to below the number of lines in the bible, i.e. by a factor of at least 20.
Worth bringing this up here for visibility. The salt-extensions migration could solve this but https://github.com/saltstack/salt/discussions/66144 would propose keeping all of the docs in salt core for extensions that get moved out
Would it make more sense to split the manpages up into different subpages? Projects like Git are a good example for this. Further Sphinx can generate to various formats that the user might want to use on their machine such as Devhelp, html or GNU Info.
Description Dear SaltStack team, I hope this tongue-in-cheek issue finds you well.
I'm not going to beat around the bush. Look at this:
(source)
My intentions when opening this issue is two-fold:
Suggested Fix I do not know.
This issue is for you to ponder, for no one has done what you did, so I consider you the only qualified party on the planet to decide how to deal with this gargantuan leviathan, which is roughly a fifth of the Encyclopædia Britannica.
Additional context Have a lovely day