[Discuss] Make it easier for users to report and fix doc errors

[dedemorton]

The underlying structure of our repos makes it hard for users and even Elastic employees to know where to go to report a doc issue. They can use the Edit link, but might feel intimidated when they see they need to open a pull request. It seems like we have all the information that we need to make this easier.

Instead of a subtle Edit icon that appears in the docs, could we have something more explicit that allows users to either edit the docs in GitHub or open an issue in the repo where the source files live?

Maybe something like:

Find an error? Fix it | Report it

This would save everyone the hassle of having to figure out how to get content updated (and reduce some internal chatter around "how do I get this updated?")

[dedemorton]

We discussed this issue during the doc huddle on 10/13/19.

• There were some folks (mostly cloud) who thought that we shouldn't ask people to create GitHub issues because we already have a big queue of those. Cloud is hoping to add a feedback mechanism to their docs, and they feel that it will provide an easier path for users who want to report issues.

• There was general agreement that making the Edit functionality more intuitive is worthwhile. We should proceed with that as part of the site redesign.

• We agreed that we would wait until the feedback mechanism is approved and see if it works before we consider adding something like a GitHub link.

I still have some concerns because the feedback mechanism doesn't fully address my original concern. It will mean more work for us because it puts the burden of opening the GitHub issues back onto us, which is sort of the opposite of what I was suggesting.

[VimCommando]

Being on the support team, I found this issue because of exactly what you're talking about: I need a documentation page updated, and I'm not clear what the "correct" process is to do so.

We would be fine opening GitHub issues, because we use those all day for other Q&A activities. Although I do understand the concern of having to manage those.

[dedemorton]

A related problem came up in a slack discussion today. @SpencerLN pointed out that our current process of asking users to create doc issues is a "big ask" especially for Beats users because we expect quite a bit. The template for Beats issues says:

Please post all questions and issues on https://discuss.elastic.co/c/beats
before opening a Github Issue. Your questions will reach a wider audience there,
and if we confirm that there is a bug, then you can open a new issue.
For security vulnerabilities please only send reports to security@elastic.co.
See https://www.elastic.co/community/security for more information.
Please include configurations and logs if available.
For confirmed bugs, please report:

• Version:
• Operating System:
• Discuss Forum URL:
• Steps to Reproduce:

@SpencerLN goes on to point out:

The above is the current process as documented in the GitHub issue template for the beats repo. To follow that process I would first need to write up a post on the Discuss forum, including sanitizing our config/logs, describing the issue in detail, and then monitor the post for X period of time, hoping that someone from Elastic sees it and replies to confirm that it is in fact a bug or docs issue. From what I gather, at that point if they confirm it is a bug, someone from Elastic would reply to my Discuss post telling me to open an issue in the public GitHub repo describing the problem and to include a link back to the Discuss post.

This feels like a contrived process for providing feedback along the lines of "the docs may not be accurate, we got this error when following them, someone may want to take a look."
One vendor that I think handles this pretty well is Microsoft, they have a feedback button on every single page of their docs that provides a simple method to provide feedback by creating a GitHub issue. Most of the content in the Issue is populated automatically when you click the button and the user only has to enter a brief description of their feedback:

[Enter feedback here]

Document Details

⚠️ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: c8e2cb79-709d-972b-6747-6d26c965fb2a
• Version Independent ID: d512ea69-a97a-e5ff-a804-6691c5dfe1e6
• Content: Create test plans and suites - Azure Test Plans
• Content Source: docs/test/create-a-test-plan.md
• Product: devops
• Technology: devops-test
• GitHub Login: @steved0x
• Microsoft Alias: sdanie
  

What should/can we do

I'm pushing for a single point of ingress (GitHub) for doc-related feedback because it is a lot of work to monitor and respond to all doc comments that come through various channels. It takes time away from writing. Here's what I think we should do:

• For the Beats repo, add a template for documentation issues. I don't think users should have to provide a link to a forum question before opening a doc issue.
• Check other repos to see if we need to add templates (there's no consistency right now across repos).
• Look into updating the existing feedback widget to enable users to open GitHub issues directly through the feedback mechanism. This might be a good spacetime project for someone.

[dedemorton]

Closing this old issue and hoping that Next Docs will solve this problem.