Update the user manual for the new unified banner.

Review Request #12880 — Created March 10, 2023 and submitted

Information

Review Board
release-6.x

Reviewers

The unified banner makes some significant improvements to some of the
core parts of the Review Board UI. This means that our user manual
needed a bunch of updates.

This change does all the text updates for the new banner. I haven't
updated any screenshots yet because the UI might get some tweaks
(especially with the "Add General Comment" action).

Built the manual and read through the output.

Summary ID
Update the user manual for the new unified banner.
The unified banner makes some significant improvements to some of the core parts of the Review Board UI. This means that our user manual needed a bunch of updates. This change does all the text updates for the new banner. I haven't updated any screenshots yet because the UI might get some tweaks (especially with the "Add General Comment" action). Testing Done: Built the manual and read through the output.
ff14101473b9fac60d8ef19d1727dda5686ddd57
Description From Last Updated

Need to document the "Add general comment" option that you recently added.

maubinmaubin

Might be good to link to the Publish Options section on the Managing and publishing drafts page.

maubinmaubin

Just my own personal preference, but I think it'd be nicer to say "By default, the banner will be in …

maubinmaubin

Just forgot an "and" here: "... in grouped mode and control all ..."

maubinmaubin

Instead of "the multiple mode" you should say "the grouped mode", to be more consistent with the wording used above. …

maubinmaubin

I think we should also mention general comments here some how.

maubinmaubin

Since you're here could you fix this typo: "have" -> "has"

maubinmaubin

The publishing-reviews page is gone now, so this will need to be updated.

maubinmaubin

This is a bit outdated, since you're here could you fix it up. To reply to a comment in a …

maubinmaubin

I think you should mention how you can select individual replies from the banner. Could mention discarding here too.

maubinmaubin

This should be in Title Case.

chipx86chipx86

This is somewhat orthogonal to this change, but I wanted to take the opportunity to bring this up. Something I'd …

chipx86chipx86

This should be Title Case.

chipx86chipx86

This should be Title Case.

chipx86chipx86

This is a good paragraph to break into bullet points (helps with SEO and scanning of text). Any time we're …

chipx86chipx86

Let's link to the Integrations page here for "chat services".

chipx86chipx86

Let's use :guilabel: here for "Publish" button.

chipx86chipx86

We don't have a page on archiving explicitly, but we have a dashboard page. That's maybe the best option for …

chipx86chipx86

Extra blank line at the end of the file.

chipx86chipx86

The comma feels a bit awkward here. Maybe: Adding comments (General Comments, Diff Comments, or File Attachment Comments) will ... …

chipx86chipx86

This could be simplified just a bit: You can also reply to the review as a whole by clicking Reply …

chipx86chipx86

This contains many different useful instructions. I think we should break the paragraph at "To publish your replies".

chipx86chipx86

Looks like this slipped in?

chipx86chipx86
maubin
  1. 
      
  2. docs/manual/users/reviews/banner.rst (Diff revision 1)
     
     
     
    Show all issues

    Need to document the "Add general comment" option that you recently added.

  3. docs/manual/users/reviews/banner.rst (Diff revision 1)
     
     
     
    Show all issues

    Might be good to link to the Publish Options section on the Managing and publishing drafts page.

  4. docs/manual/users/reviews/drafts.rst (Diff revision 1)
     
     
    Show all issues

    Just my own personal preference, but I think it'd be nicer to say "By default, the banner will be in grouped mode and control all active drafts"

  5. docs/manual/users/reviews/drafts.rst (Diff revision 1)
     
     
    Show all issues

    Instead of "the multiple mode" you should say "the grouped mode", to be more consistent with the wording used above.

    Also shouldn't the :guilabel: on this line be "Publish All" instead of "Publish"?

  6. docs/manual/users/reviews/editing-reviews.rst (Diff revision 1)
     
     
     
     
    Show all issues

    I think we should also mention general comments here some how.

  7. Show all issues

    Since you're here could you fix this typo: "have" -> "has"

  8. Show all issues

    The publishing-reviews page is gone now, so this will need to be updated.

    1. The old page itself is gone but the ref still exists on the new drafts page.

  9. docs/manual/users/reviews/replying.rst (Diff revision 1)
     
     
     
     
     
    Show all issues

    This is a bit outdated, since you're here could you fix it up. To reply to a comment in a review, you click on the "Reply" button that's under the comment.

    You can also make a general reply to a review, not linked to a comment. If the review does not have a header, there's a "Comment" button displayed at the top of the review that you can use to write a reply. If the review has a header, there is no "Comment" button, instead there is a "Reply" button under the header that you can use to write the reply.

    1. Eep, wonder how long this has been out of date.

  10. docs/manual/users/reviews/replying.rst (Diff revision 1)
     
     
     
     
     
    Show all issues

    I think you should mention how you can select individual replies from the banner. Could mention discarding here too.

  11. 
      
david
maubin
  1. Looks good :)

  2. docs/manual/users/reviews/drafts.rst (Diff revisions 1 - 2)
     
     
    Show all issues

    Just forgot an "and" here: "... in grouped mode and control all ..."

  3. 
      
david
chipx86
  1. This looks great. There's a couple small consistency things, but the big-ticket items are less about this change and about our docs as a whole going forward, with an eye toward SEO.

    Google rewards clear, concise paragraphs that are focused on a topic, and bullet points for options pertaining to leading text. Basically, if it eases scannability when reading content, it can benefit search results. Smaller paragraphs, shorter sentences, less complexity, visual separation, consistent naming, and consistent linking to topics can all help.

    We have a lot of opportunities to make this happen in our docs. When we have a list of choices or multiple concepts/options for something in one paragraph, we should consider breaking them out into multiple paragraphs or bullet points.

    (In general, bullet points seem to be rewarded these days.)

    I pointed out a couple spots I think could convert well to that.

  2. docs/manual/users/reviews/banner.rst (Diff revision 3)
     
     
    Show all issues

    This should be in Title Case.

  3. docs/manual/users/reviews/banner.rst (Diff revision 3)
     
     
    Show all issues

    This is somewhat orthogonal to this change, but I wanted to take the opportunity to bring this up.

    Something I'd like to start doing with our public documentation is properly naming aspects of our product and capitalizing them whenever we refer to them.

    For example:

    • "Review Dialog" instead of "review dialog"
    • "General Comment" instead of "general comment"
    • "Draft Banner" instead of "draft banner".

    These are specific entities in our product we're referring to. It's not a review dialog, it's the Review Dialog.

    This would help them visually stand out in text and in search results, help with scanning for text, and hopefully help readers build a mental map of what's what in the UI.

  4. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
    Show all issues

    This should be Title Case.

  5. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
    Show all issues

    This should be Title Case.

  6. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
     
     
     
     
    Show all issues

    This is a good paragraph to break into bullet points (helps with SEO and scanning of text). Any time we're describing multiple options Something like:

    When the banner is in grouped mode, you have the following options for publishing:
    
    * To publish all active drafts and blah blah, click :guilabel:`Publish All`.
    * To publish or discard blah blah ...
    

    The more we can do this, laying out options or steps or multiple choices in list form, the better our chances for Google to turn them into smarter search results. Also, just helps break up sections full of paragraphs.

  7. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
    Show all issues

    Let's link to the Integrations page here for "chat services".

  8. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
    Show all issues

    Let's use :guilabel: here for "Publish" button.

  9. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
    Show all issues

    We don't have a page on archiving explicitly, but we have a dashboard page. That's maybe the best option for now. Let's link to it: star-archive-and-mute.

  10. docs/manual/users/reviews/drafts.rst (Diff revision 3)
     
     
     
    Show all issues

    Extra blank line at the end of the file.

  11. Show all issues

    The comma feels a bit awkward here. Maybe:

    Adding comments (General Comments, Diff Comments, or File Attachment Comments) will ...
    

    With refs to each of the sections.

  12. docs/manual/users/reviews/replying.rst (Diff revision 3)
     
     
     
     
    Show all issues

    This could be simplified just a bit:

    You can also reply to the review as a whole by clicking Reply under the review header. If there is no header text, ...
    
  13. docs/manual/users/reviews/replying.rst (Diff revision 3)
     
     
     
     
     
     
    Show all issues

    This contains many different useful instructions. I think we should break the paragraph at "To publish your replies".

  14. 
      
david
chipx86
  1. 
      
  2. Show all issues

    Looks like this slipped in?

  3. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to release-6.x (7122e9f)