Update the documentation on using the Review Dialog.

Review Request #9320 — Created Oct. 24, 2017 and submitted

Information

Review Board
release-3.0.x
53870fd...

Reviewers

This fleshes out the Review Dialog's documentation, going into how to
manage (edit and delete) comments, write a header/footer, add General
Comments, and a blurb on adding diff/file attachment comments
(referencing the correct docs for those).

Screenshots were added to help show off the different aspects of the
dialog.

Built the docs. No errors, except for references to the General Comments
docs, which don't yet exist (they're in progress).

Checked for spelling errors.

Checked that Retina/non-Retina screenshots were pixel-aligned.

Description From Last Updated

I'm not sure "Review Dialog" should be title cased. We don't even title case "Review Request". Here and throughout.

daviddavid

Maybe clarify "unpublished review"? As it is it's maybe possible people might think it would delete published comments.

daviddavid
david
  1. 
      
  2. Show all issues

    I'm not sure "Review Dialog" should be title cased. We don't even title case "Review Request". Here and throughout.

    1. Oh, that was kinda intentional. I've been changing that in other files too. Wanted it to have more of a formal name to help that stand out and be more clear when referencing it. With the new UI being planned, I intended to give it a formal "Review Composer" name, anyway. I guess I can change it though.

    2. Let's change it for now and revisit next time. If we want to do "Review Composer" we should do "Review Request", though.

    3. We could do that, but I feel like review requests are more of a concept, whereas the dialog is an identifiable piece of UI that has a name. You don't write the "system preferences" dialog, you write "System Preferences", even if you might otherwise write "preferences."

    4. In the case you cite, "System Preferences" would be the title of the window, and therefore it would be appropriate to match the casing in the UI.

    5. I'm changing it back because I don't want to get bogged down with it right now, but I do want to understand the argument better. In this example, "System Preferences" is the title of the window, yes, but also the name of that specific dialog, not a class of dialogs. It's an identifiable entity in the product that goes by a specific name. Just like the My Account page, Administration UI, and the Review Dialog. Why isn't it appropriate to reference in Title Case?

  3. Show all issues

    Maybe clarify "unpublished review"? As it is it's maybe possible people might think it would delete published comments.

  4. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-3.0.x (0b2fd23)