theforeman
An 'inline issue reporting' feature for docs.theforeman.org
Introduce a feature that allows users to highlight text within the documentation and makes it easy to immediately create a comment with feedback: issue, or perhaps an option to start a topic in Discourse.
Generally speaking, I think an easy way of creating issues is a good idea. It encourages feedback and could help us identify and clarify potentially problematic parts of our docs.
Right now, I can see two ways to implement it that could be relatively easy, although without the 'inline' element that was part of the original idea:
- Follow up on https://github.com/theforeman/foreman-documentation/pull/3670#issuecomment-3121620482 and add a link to the top navigation bar.
- Follow up on https://github.com/theforeman/foreman-documentation/pull/3653/files and add a new ribbon to the bottom right corner of the page.
Either the link in the navigation menu or the ribbon could serve as links that would immediately open the form to create a GitHub issue. Such an issue could include a pre-defined template (for example, inviting users to copy-paste the paragraph they're reading) and could immediately be associated with an issue label (like 'direct user feedback').
I think we could include a "descriptive" icon inside the triangle defined by the ribbon. Unlike the ribbon, it should be displayed for all supported releases I suppose?
I'm a bit worried we might get overwhelmed by feedback issues, but I agree that it's better to collect them upstream before they bubble downstream.
Some frameworks also support mapping content to Web IDEs of the docs. Example: You view "Registering a host", click the edit icon, and end up on https://github.com/theforeman/foreman-documentation/edit/master/guides/common/modules/proc_registering-a-host.adoc or even https://github.dev/theforeman/foreman-documentation/edit/master/guides/common/modules/proc_registering-a-host.adoc (I never did this before)
Some frameworks also support mapping content to Web IDEs of the docs. Example: You view "Registering a host", click the edit icon, and end up on https://github.com/theforeman/foreman-documentation/edit/master/guides/common/modules/proc_registering-a-host.adoc or even https://github.dev/theforeman/foreman-documentation/edit/master/guides/common/modules/proc_registering-a-host.adoc (I never did this before)
Asciidoctor docs site has that: https://docs.asciidoctor.org/ See "Edit this Page" in the top right corner. That would be cool but the question is how to implement this.
https://github.com/theforeman/foreman-documentation/pull/4098 explores the option to add a ribbon with a link to open a new issue. I'd consider this good enough for now and in the future, replacing the link to open a new issue with a link to edit the page would be an option.
https://docs.asciidoctor.org/ uses Antora, so I assume that this is either possible in Antora by default, or via open source plugin/extension.
About adding a link to open a pre-filled issue: This is the feature -- https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository -- and it depends on having access to a repository's Settings. I don't have that so in https://github.com/theforeman/foreman-documentation/pull/4098, I'm implementing a link to a blank issue only. That should be enough for now and we can potentially work on adding an issue template later, if there is interest.
Asciidoctor docs site has that: https://docs.asciidoctor.org/ See "Edit this Page" in the top right corner. That would be cool but the question is how to implement this.
I really love this idea, but due to modular docs it's really hard to implement. Unlike asciidoc's website, we don't have a single .adoc file you can edit. I'm not sure where you would link to.
About adding a link to open a pre-filled issue: This is the feature -- https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository -- and it depends on having access to a repository's Settings. I don't have that so in #4098, I'm implementing a link to a blank issue only. That should be enough for now and we can potentially work on adding an issue template later, if there is interest.
All that feature does is create some UI around plain text files. Quoting https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
In your repository, create a file called .github/ISSUE_TEMPLATE/FORM-NAME.yml, replacing FORM-NAME with the name for your issue form. For more information about creating new files on GitHub, see Creating new files.
So you don't need an admin. You can create those form YAML files in your own fork and then submit a PR.
