MantisBT - Open CASCADE
View Issue Details
0029817Open CASCADE[OCCT] OCCT:Documentationpublic2018-05-27 13:472018-07-30 10:27
abv 
bugmaster 
normalminor 
closedfixed 
 
[OCCT] 7.4.0[OCCT] 7.4.0 
Not needed
0029817: Documentation - avoid excessive use of "please"
The word "please" is used in ~ 50 places across OCCT documentation, and in most of these places it looks excessive. "Please" is good in direct messages to particular persons (e.g. in e-mail) when you ask for something, but not in technical documents intended for wide audience when you just provide information.

See for instance Google style guide:
https://developers.google.com/style/tone#politeness-and-use-of-please [^]

Even more, when "please" is still useful, use of comma after it should be avoided except when it is really necessary. Note that normally comma is not needed after "please" in English, and when it is present, it emphasizes this as strong request. We unlikely need to have such requests in our docs. More detailed explanations can be found elsewhere, e.g.:
https://english.stackexchange.com/questions/389/in-what-cases-should-i-use-a-comma-after-please [^]
NA
No tags attached.
Issue History
2018-05-27 13:47abvNew Issue
2018-05-27 13:47abvAssigned To => ysn
2018-07-09 13:54gitNote Added: 0077393
2018-07-09 13:54ysnAssigned Toysn => abv
2018-07-09 14:00ysnNote Added: 0077394
2018-07-09 14:00ysnStatusnew => resolved
2018-07-09 14:00ysnSteps to Reproduce Updatedbug_revision_view_page.php?rev_id=19448#r19448
2018-07-12 18:16abvNote Added: 0077548
2018-07-12 18:16abvAssigned Toabv => bugmaster
2018-07-12 18:16abvStatusresolved => reviewed
2018-07-12 18:43bugmasterStatusreviewed => tested
2018-07-14 12:26bugmasterChangeset attached => occt master 07f2b741
2018-07-14 12:26bugmasterStatustested => verified
2018-07-14 12:26bugmasterResolutionopen => fixed
2018-07-14 12:42gitNote Added: 0077616
2018-07-30 10:27bugmasterTest case number => Not needed

Notes
(0077393)
git   
2018-07-09 13:54   
Branch CR29817 has been created by ysn.

SHA-1: b93ddf5104997586921e70244f001b936d04801f


Detailed log of new commits:

Author: ysn
Date: Mon Jul 9 13:53:01 2018 +0300

    "Please" is now used in the documentation only in sensitive cases. Some punctuation issues have been fixed.
(0077394)
ysn   
2018-07-09 14:00   
Done as requested. It is a question of shifting approach. Same as avoiding to capitalize "вы" in all cases in Russian.
"Please" remains in a few cases when the requested actions pose some inconveniences, such as contacting us about license, or reporting bugs.
(0077548)
abv   
2018-07-12 18:16   
Reviewed, please integrate
(0077616)
git   
2018-07-14 12:42   
Branch CR29817 has been deleted by inv.

SHA-1: b93ddf5104997586921e70244f001b936d04801f