add a feedback link to each documentation page

[wrabbit-revisited]

Sometimes i run into issues which could be avoided via documentation, but there doesn't appear to be an easy way to provided suggested improvements on the page in question. If there was it might lead to rapid incremental improvement.

Couchbase has this feature as do many wikis.
http://docs.couchbase.com/admin/admin/Couchbase-intro.html

[wrabbit-revisited]

i.e. #5338

The page at http://docs.saltstack.com/en/latest/topics/mine/ doesn't seem to mention the need for something like:

/srv/pillar/saltmine.sls

mine_functions:
  network.interfaces: []
  network.ip_addrs: []

Just saying.. perhaps not a high priority, but if there was a feedback option users could add edits then/there instead of using IRC or forums and you could probably significantly reduce errors from users straying off the path.

[jfindlay]

The documentation is included in the salt repo, so if you have improvements or corrections, you are welcome to submit a pull request. Is this a sufficient mechanism for what you were thinking of? We are also in the process of reworking the documentation site although I am not directly involved in that effort.

[iggy]

A link to the github source file that generated the current page might be a good addition.

i.e. http://docs.saltstack.com/en/latest/ref/states/top.html links to https://github.com/saltstack/salt/blob/develop/doc/ref/states/top.rst somehow

[wrabbit-revisited]

Crowdsourcing documentation has been a common theme for the past few years. The idea is to make it very easy for the community to quickly and intuitively interact with other members and the doc team when they run across an issue. It should be quite easy to use, like MediaWiki or maybe something like readme.io (which will host open source projects for free btw). Generally just an interface that allows a user to quickly suggest a change when they run into an issue right at the point where the issue occurs as opposed to sticking it into something like this where the context is easily lost.

[jfindlay]

These are all good ideas, thanks.

[gravyboat]

This would be cool to see. The feedback page could simply interface with GitHub to automatically create an issue, then provide the user with that link back. A new automated user would need to be created, but I think this is both doable and a good idea for those reading the docs who aren't familiar with GitHub.

[jfindlay]

@wrabbit-revisited, @iggy, @gravyboat, @rominf, the easiest thing to do here, in addition to the option to file an issue, would be to link directly to the edit feature on githib from the docs site. For example, the state tutorial would link to the github edit page for that document, from which sending in a pull request is almost a one step process. The downside is that this assumes the user has a github profile.

[gravyboat]

@jfindlay Yeah that's why I was proposing a 'doc_feedback_bot' or something was created that would just create the issue when the user reported it. In many instances I'm sure the user doesn't have the expertise or familiarity to fix the problem with the docs, and is instead just confused by layout or wording.

[iggy]

I suspect the number of people that would actually use the "report issue with this page" feature has a pretty high intersection with people who have github accounts. At the very least it seems like a simple first step toward increasing users helping fix issues. I know I would use it often enough... as it is now, I cba to track down where the docs for different pages are.

[DanyC97]

this is great idea and honestly i'm on same side with @iggy, is not a big deal to get a github account should you want to contribute.
IS a minimal effort from the community to give back to Salt as a company/ project.

[gravyboat]

It's still a step that is required to provide feedback. I know that I wouldn't do that if I didn't already have an account. A great example of this lately was feedback for DO's new IP feature which I had feedback on and they asked me to submit to some service I would have had to sign up for which I did not do. If you want feedback you need to provide the lowest possible barrier to entry, and requiring users to create a GitHub account doesn't create that sort of environment.

[DanyC97]

@gravyboat right but the way i'm thinking is in terms of baby steps

• 1st get the feedback out asap even if that require GitHub account, is no brainer to enable it, minimal effort
• 2nd based on lessons learned lower the barrier and get rid of the GitHub account, requires more design around it i believe

Currently the barrier is higher and we need to gradually lower it ..my £0.002

[gravyboat]

@DanyC97 I think that's pretty fair and agree it would be easy to add a 'have feedback? Report it to us!' and a link directly to the new issues. I just want to make sure that this isn't the only step taken as it isn't sufficient to get the sort of engagement that is needed from your average user of the docs.

[DanyC97]

👍

[gravyboat]

Hmm, I just double checked what that process would look like while not logged in (realized I've never even navigated to the repo without being logged in) and it's actually a pretty crappy user experience:

There's no prompt to create an account, all you can do is log in.

[jfindlay]

Another issue (although I'm not responding to discourage anything) is that even if the user is (already) successfully logged into github, they'll be presented with some potentially very dense rst markup. Again, this may not be too much of a problem since most salt users have high technical competence and could infer most things for minor changes from context.

[rominf]

I think that people, which use Salt, are capable to learn rst markup or write docstrings for Salt functions, moreover GitHub is quite popular and has convenient interface for single file edits contributing. Adding a link to corresponding sources (as described in #27618) has additional benefit — in case of incomplete documentation I can deduce what function does from sources. I do it quite often and it's not very convenient, because now I need to search required file, function either in Salt repo on my PC, or in github.com repo and it takes time.

[DanyC97]

and for those who would like to see a real example of what i was saying earlier, check Elastic docs - very high quality imo

https://www.elastic.co/guide/en/elasticsearch/reference/2.0/breaking_20_mapping_changes.html#_field_names_may_not_contain_dots

where you should see the edit button - straight and simple

[DanyC97]

few good weeks past and we entered into a new year. Are you going to do anything about this?

Note Ansible has the same thing so don't get it why we are waiting for?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

If this issue is closed prematurely, please leave a comment and we will gladly reopen the issue.