[DOCS] The salt(7) man page is one order of magnitude larger than any man page on the planet

[sebastiancarlos]

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:

1. To offer my congratulations.
2. To bring this to your attention. There are not many conventions on how to structure man pages, and indeed there is some advantage in dumping all of one's documentation into a man page for easier global search. Still, I do wonder if we, as Homo Sapiens, have gone too far on this one.

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

[welcome]

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:

• Community Wiki
• Salt’s Contributor Guide
• Join our Community Slack
• IRC on LiberaChat
• Salt Project YouTube channel
• Salt Project Twitch channel

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!

[barbaricyawps]

@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.

[mthibaut]

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.

[ITJamie]

Worth bringing this up here for visibility. The salt-extensions migration could solve this but #66144 would propose keeping all of the docs in salt core for extensions that get moved out