Enhanced Documentation Review Process

[sachin-suresh-rapyuta]

What's the problem this feature will solve?

During the review process, it is crucial for reviewers to efficiently assess and understand the changes made to the documentation. Currently, navigating to specific changes requires manually searching for the file within the ReadtheDocs documentation structure, which can be time-consuming and detracts from the review experience.

Describe the solution you'd like

1. Direct Navigation to Modified Content:

When accessing a doc build preview link, the user should be taken directly to the portion of the documentation where changes have been made. This direct navigation ensures that reviewers can immediately focus on the content that requires their attention.

2. Differential Highlighting:

Changes made to the RST or MD files should be visually highlighted within the documentation preview. This highlighting could take the form of color coding or other visual indicators that distinctly mark added, modified, or removed content. By clearly delineating changes, reviewers can more easily assess and provide feedback on the modifications.

[humitos]

Thanks for opening this issue with a proposed feature 👍🏼

Direct Navigation to Modified Content:
When accessing a doc build preview link, the user should be taken directly to the portion of the documentation where changes have been made. This direct navigation ensures that reviewers can immediately focus on the content that requires their attention.

We've talked about this in multiple opportunities and we've found it's not easy/trivial to implement in a reliable way. One of those conversations is at readthedocs/actions#4, in case you want to have more context.

I'm happy to receive detailed feedback about how you imagine this feature could be implemented considering what we discussed already and its UX exposed to users.

Differential Highlighting:
Changes made to the RST or MD files should be visually highlighted within the documentation preview. This highlighting could take the form of color coding or other visual indicators that distinctly mark added, modified, or removed content. By clearly delineating changes, reviewers can more easily assess and provide feedback on the modifications.

We have a beta implementation of this feature already as part of the "Read the Docs Addons". If you have beta addons enabled in your project¹, navigating to a page that is modified in the PR preview and pressing d in the keyboard should show a visual diff integrated on the page.

Example:

Let me know any feedback you may have about the visual docdiff feature. You can open an issue at https://github.com/readthedocs/addons which it's the official repository for it.

Footnotes

1. to enable the addons on your project, follow these steps: https://github.com/readthedocs/readthedocs.org/issues/7732#issuecomment-1991957454 ↩

[stsewd]

When accessing a doc build preview link, the user should be taken directly to the portion of the documentation where changes have been made. This direct navigation ensures that reviewers can immediately focus on the content that requires their attention.

I think a similar solution to what I described in #6621 (comment) can be useful here. We can detect the new pages added in a PR, and we could even go further and sort pages by number of changes after running a diff, that way we work over the resulted pages instead of trying to guess from the source files.

[sachin-suresh-rapyuta]

I'm happy to receive detailed feedback about how you imagine this feature could be implemented considering what we discussed already and its UX exposed to users.

Here are some feedbacks/suggestions:

How it can be implemented?

1. Change Detection:

• Utilize Git or similar version control systems integrated with RTD to detect changes between builds.
• Identify modified .rst files (or other documentation source files) in a commit or across a range of commits. Something like what @stsewd suggested.

2. Link Generation:

• Generate direct links to the corresponding sections/pages in the RTD build preview for each detected change.

• Adjust file paths to match the URL structure of the RTD preview site. This may involve stripping base directory names (like docs/) and converting file paths to pretty URLs.

3. Configuration Options:

• Allow project maintainers to configure the maximum number of direct links displayed to prevent flooding the interface when numerous changes are detected.

• Provide options in RTD project settings for customizing URL conversion rules (e.g., how to handle directory names, and file extensions).

UX Improvement suggestions

1. Configuration UI:

In the RTD project settings, include a user-friendly UI for configuring the direct navigation feature, such as specifying the maximum number of direct links to display and setting URL conversion rules.

2. Feedback Mechanism:

Incorporate a way for reviewers to provide feedback directly from the build preview interface, such as comments or suggestions on the modified sections. This could be integrated with the project's issue tracking system. This could greatly improve the review process.

3. Visual Indicators:

I think this is already a part of the Beta implementation.

Let me know what you think.

[humitos]

Thanks for the detailed explanation about how this feature could work/be implemented.

I see how 1) could be implemented inside the GitHub action I linked before. It seems it has all the information required and the specific data needed from the users can be requested via the GitHub Action YAML configuration file (maximum number of links, how to convert from source file, like .rst, to an URL, etc).

Incorporate a way for reviewers to provide feedback directly from the build preview interface, such as comments or suggestions on the modified sections

We've talked a lot about this in the past and we found it's pretty complex to implement in a nice and usable way. There is a related issue with similar conversation at readthedocs/addons#89

It seems we are already tracking these ideas on specific issues already, so I will proceed to close this one for now. Please, subscribe there if you want to keep up to date with the news.