Update the user manual for the new unified banner.
Review Request #12880 — Created March 10, 2023 and submitted
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 |
---|---|
ff14101473b9fac60d8ef19d1727dda5686ddd57 |
Description | From | Last Updated |
---|---|---|
Need to document the "Add general comment" option that you recently added. |
maubin | |
Might be good to link to the Publish Options section on the Managing and publishing drafts page. |
maubin | |
Just my own personal preference, but I think it'd be nicer to say "By default, the banner will be in … |
maubin | |
Just forgot an "and" here: "... in grouped mode and control all ..." |
maubin | |
Instead of "the multiple mode" you should say "the grouped mode", to be more consistent with the wording used above. … |
maubin | |
I think we should also mention general comments here some how. |
maubin | |
Since you're here could you fix this typo: "have" -> "has" |
maubin | |
The publishing-reviews page is gone now, so this will need to be updated. |
maubin | |
This is a bit outdated, since you're here could you fix it up. To reply to a comment in a … |
maubin | |
I think you should mention how you can select individual replies from the banner. Could mention discarding here too. |
maubin | |
This should be in Title Case. |
chipx86 | |
This is somewhat orthogonal to this change, but I wanted to take the opportunity to bring this up. Something I'd … |
chipx86 | |
This should be Title Case. |
chipx86 | |
This should be Title Case. |
chipx86 | |
This is a good paragraph to break into bullet points (helps with SEO and scanning of text). Any time we're … |
chipx86 | |
Let's link to the Integrations page here for "chat services". |
chipx86 | |
Let's use :guilabel: here for "Publish" button. |
chipx86 | |
We don't have a page on archiving explicitly, but we have a dashboard page. That's maybe the best option for … |
chipx86 | |
Extra blank line at the end of the file. |
chipx86 | |
The comma feels a bit awkward here. Maybe: Adding comments (General Comments, Diff Comments, or File Attachment Comments) will ... … |
chipx86 | |
This could be simplified just a bit: You can also reply to the review as a whole by clicking Reply … |
chipx86 | |
This contains many different useful instructions. I think we should break the paragraph at "To publish your replies". |
chipx86 | |
Looks like this slipped in? |
chipx86 |
-
-
-
-
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"
-
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"? -
-
-
-
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.
-
I think you should mention how you can select individual replies from the banner. Could mention discarding here too.
- Commits:
-
Summary ID abb2b4abfa4d3c6f02c850e988f648bcaa4a9e73 1a9a86160aba47d27bae5616e31bd39df28bf9d8 - Diff:
-
Revision 2 (+290 -180)
Checks run (2 succeeded)
- Commits:
-
Summary ID 1a9a86160aba47d27bae5616e31bd39df28bf9d8 53c268140eaa12559b20955230aeaf1252c615df - Diff:
-
Revision 3 (+290 -180)
Checks run (2 succeeded)
-
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.
-
-
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.
-
-
-
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.
-
-
-
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
. -
-
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.
-
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, ...
-
This contains many different useful instructions. I think we should break the paragraph at "To publish your replies".
- Commits:
-
Summary ID 53c268140eaa12559b20955230aeaf1252c615df ff14101473b9fac60d8ef19d1727dda5686ddd57 - Diff:
-
Revision 4 (+308 -182)