Update the user manual for the new unified banner.

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

david
Review Board
release-6.x
reviewboard

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
Update the user manual for the new unified banner.
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)
     
     
     

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

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

    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)
     
     

    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)
     
     

    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)
     
     
     
     

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

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

  8. 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)
     
     
     
     
     

    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)
     
     
     
     
     

    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)
     
     

    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)
     
     

    This should be in Title Case.

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

    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)
     
     

    This should be Title Case.

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

    This should be Title Case.

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

    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)
     
     

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

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

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

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

    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)
     
     
     

    Extra blank line at the end of the file.

  11. 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)
     
     
     
     

    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)
     
     
     
     
     
     

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

  14. 
      
david
chipx86
  1. 
      
  2. Looks like this slipped in?

  3. 
      
david
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to release-6.x (7122e9f)
Loading...