Update the documentation on using the Review Dialog.

 






 

 


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

 


















 

  

   Information

  





 
 

  chipx86
 









 
 

  Review Board
 









 
 

  release-3.0.x
 









 
 

  
 









 
 

  
 









 
 

  53870fd...
 






 




 

  

   Reviewers

  





 
 

  reviewboard
 









 
 

  
 






 








 





  


 
 

  
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




   

   







  

 



 

  


   

   

    
 
david


    
   


  

  

  



    




  1. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 

















  2. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/manual/users/reviews/editing-reviews.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   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. 



    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. 



    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. 



    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. 



    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?
      
 
      

      6. 


 
    


    

 
    

    3. 






  3. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/manual/users/reviews/editing-reviews.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



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

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    4. 




  4. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    5. 




  

 
















 



 

  

   




chipx86




   

   

  

 



 















 





 

  

   




david




   

   







  

 



 

  


   

   

    
 
david


    
   


  

  

  



    




  1. 
 
    
  
    
   
    Ship It!
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 















  2. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3. 




  

 
















 



 

  

   




chipx86




   

   

  

 



 

  


   

   

    
 Review request changed

    
   


  

  

  







  

   

    Status:
   

   


    Completed

   

  




  

   

    Change Summary:
   

   

    
Pushed to release-3.0.x (0b2fd23)