Update and improve docs for new changes in RB6.

Review Request #13299 — Created Oct. 4, 2023 and submitted

Information

Review Board
release-6.x

Reviewers

We have a lot of new UI and user experience changes in RB6, so it was
necessary to do an overview of the docs to make sure everything is up to date.
This change updates any screenshots that were affected by our UI changes, and
fleshes out some documentation for file attachments and review requests.

Note: The screenshots in this change are not perfect and are just
placeholders. They should be replaced with new screenshots in a later
change.

Built the docs, made sure the new screenshots looked good, checked that all new
refs worked, and checked for spelling errors.

Summary ID
Update and improve docs for new changes in RB6.
c40422ae82526d68db6539fc869acb4e0751774b
Description From Last Updated

Let's add a comma before "then browse"

daviddavid

Extra blank line at the end of the file.

chipx86chipx86

Two blank lines here.

chipx86chipx86

Two blank lines here.

chipx86chipx86

For each new image, we should do the following: Set :width: <value> to help define a width for the image …

chipx86chipx86

The --> was wrong before. It should just be ->. That'll get styled correctly.

chipx86chipx86

This may be a good candidate for converting to numeric lists of steps, even though it's not a long list. …

chipx86chipx86

Extra blank line at the end of the file.

chipx86chipx86
david
  1. 
      
  2. Show all issues

    Let's add a comma before "then browse"

  3. 
      
maubin
david
  1. Ship It!
  2. 
      
chipx86
  1. Thanks for going through this! Looks great. There's a few spacing/blank line nits, some suggestions for improving .. image:, and just a content suggestion.

  2. Show all issues

    Extra blank line at the end of the file.

  3. docs/manual/users/review-requests/publishing.rst (Diff revision 2)
     
     
     
     
    Show all issues

    Two blank lines here.

  4. docs/manual/users/review-requests/publishing.rst (Diff revision 2)
     
     
     
     
    Show all issues

    Two blank lines here.

  5. Show all issues

    For each new image, we should do the following:

    1. Set :width: <value> to help define a width for the image element, which will then be used to constrain the image's bounding box in the generated docs (the height is taken care of for you).
    2. Set :alt: for accessible text. It should describe what's in the image for those who can't see it. See docs/releasenotes/6.0-beta-3.rst for examples here.
  6. Show all issues

    The --> was wrong before. It should just be ->. That'll get styled correctly.

    1. I think it should be -->, that's what it says on the Sphinx docs and all of our other :menuselection: follow this.

  7. docs/manual/users/review-requests/uploading-files.rst (Diff revision 2)
     
     
     
     
     
     
     
    Show all issues

    This may be a good candidate for converting to numeric lists of steps, even though it's not a long list.

    Any time we have multiple steps or options or concepts in one paragraph, it's a good candidate for breaking that up into a more scannable form. Bullet points or numeric lists are a good option when they're all related. When they're separate options, different paragraphs can be good.

    That can be useful for people just scanning a page, especially if English isn't their first option. But also, Google actually rewards this sort of formatting, sometimes showing it as answers in search results (which promotes the page in the process).

  8. Show all issues

    Extra blank line at the end of the file.

  9. 
      
maubin
chipx86
  1. Ship It!
  2. 
      
maubin
Review request changed
Status:
Completed
Change Summary:
Pushed to release-6.x (de732b6)