{"action":"opened","issue":{"url":"https://api.github.com/repos/saltstack/salt/issues/20066","labels_url":"https://api.github.com/repos/saltstack/salt/issues/20066/labels{/name}","comments_url":"https://api.github.com/repos/saltstack/salt/issues/20066/comments","events_url":"https://api.github.com/repos/saltstack/salt/issues/20066/events","html_url":"https://github.com/saltstack/salt/issues/20066","id":55531872,"number":20066,"title":"Add more cross-references between state and execution module docs","user":{"login":"whiteinge","id":91293,"avatar_url":"https://avatars.githubusercontent.com/u/91293?v=3","gravatar_id":"","url":"https://api.github.com/users/whiteinge","html_url":"https://github.com/whiteinge","followers_url":"https://api.github.com/users/whiteinge/followers","following_url":"https://api.github.com/users/whiteinge/following{/other_user}","gists_url":"https://api.github.com/users/whiteinge/gists{/gist_id}","starred_url":"https://api.github.com/users/whiteinge/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/whiteinge/subscriptions","organizations_url":"https://api.github.com/users/whiteinge/orgs","repos_url":"https://api.github.com/users/whiteinge/repos","events_url":"https://api.github.com/users/whiteinge/events{/privacy}","received_events_url":"https://api.github.com/users/whiteinge/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/saltstack/salt/labels/Documentation","name":"Documentation","color":"0052cc"},{"url":"https://api.github.com/repos/saltstack/salt/labels/Pending%20Discussion","name":"Pending Discussion","color":"bfdadc"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/saltstack/salt/milestones/13","labels_url":"https://api.github.com/repos/saltstack/salt/milestones/13/labels","id":9265,"number":13,"title":"Approved","description":"All issues that are ready to be worked on, both bugs and features.","creator":{"login":"thatch45","id":507599,"avatar_url":"https://avatars.githubusercontent.com/u/507599?v=3","gravatar_id":"","url":"https://api.github.com/users/thatch45","html_url":"https://github.com/thatch45","followers_url":"https://api.github.com/users/thatch45/followers","following_url":"https://api.github.com/users/thatch45/following{/other_user}","gists_url":"https://api.github.com/users/thatch45/gists{/gist_id}","starred_url":"https://api.github.com/users/thatch45/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/thatch45/subscriptions","organizations_url":"https://api.github.com/users/thatch45/orgs","repos_url":"https://api.github.com/users/thatch45/repos","events_url":"https://api.github.com/users/thatch45/events{/privacy}","received_events_url":"https://api.github.com/users/thatch45/received_events","type":"User","site_admin":false},"open_issues":1857,"closed_issues":1456,"state":"open","created_at":"2011-05-14T04:00:56Z","updated_at":"2015-01-26T20:19:13Z","due_on":null,"closed_at":null},"comments":0,"created_at":"2015-01-26T20:19:13Z","updated_at":"2015-01-26T20:19:13Z","closed_at":null,"body":"Adding cross-references from state module docs to the execution modules they call would improve discoverability and reduce the appearance of magic in the state system. Discuss options for how to approach this below:\r\n\r\n**Option one**: keep things high-level and add top-level `seealso` directives to related modules. Add these cross-references to the module-level documentation and not the individual function documentation.\r\n\r\nPros: simple.\r\nCons: not as detailed or helpful.\r\n\r\n**Option two**: add _some_ cross references at the function-level where it makes sense and helps with understanding.\r\n\r\nPros: more specific, helps illustrate the relationship between execution functions and state functions.\r\nCons: Tough not overwhelm the reader. There isn't usually a direct one-to-one relationship. (Sometimes there is (`file.replace` does and `file.manage_file` almost does) but I those are rare.) A good example is the ostensibly simple `user.absent` and `user.present` state functions. Just those two state functions call no less than 26 execution functions across the file, group, shadow, and user execution modules both for pre-checks and to alter the system.\r\n\r\nOther options or thoughts?"}}