View Issue Details

IDProjectCategoryView StatusLast Update
0029817Open CASCADEOCCT:Documentationpublic2018-07-30 10:27
Reporterabv Assigned Tobugmaster  
PrioritynormalSeverityminor 
Status closedResolutionfixed 
Target Version7.4.0Fixed in Version7.4.0 
Summary0029817: Documentation - avoid excessive use of "please"
DescriptionThe 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
Steps To ReproduceNA
TagsNo tags attached.
Test case numberNot needed

Activities

git

2018-07-09 13:54

administrator   ~0077393

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.

ysn

2018-07-09 14:00

developer   ~0077394

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.

abv

2018-07-12 18:16

manager   ~0077548

Reviewed, please integrate

git

2018-07-14 12:42

administrator   ~0077616

Branch CR29817 has been deleted by inv.

SHA-1: b93ddf5104997586921e70244f001b936d04801f

Related Changesets

occt: master 07f2b741

2018-07-09 10:53:01

ysn


Committer: bugmaster Details Diff
0029817: Documentation - avoid excessive use of "please"

"Please" is now used in the documentation only in sensitive cases.
Affected Issues
0029817
mod - dox/dev_guides/documentation/documentation.md Diff File
mod - dox/dev_guides/git_guide/git_guide.md Diff File
mod - dox/dev_guides/upgrade/upgrade.md Diff File
mod - dox/overview/overview.md Diff File
mod - dox/technical_overview/technical_overview.md Diff File
mod - dox/user_guides/boolean_operations/boolean_operations.md Diff File
mod - dox/user_guides/draw_test_harness/draw_test_harness.md Diff File
mod - dox/user_guides/foundation_classes/foundation_classes.md Diff File
mod - dox/user_guides/iges/iges.md Diff File
mod - dox/user_guides/inspector/inspector.md Diff File
mod - dox/user_guides/modeling_algos/modeling_algos.md Diff File
mod - dox/user_guides/modeling_data/modeling_data.md Diff File
mod - dox/user_guides/shape_healing/shape_healing.md Diff File
mod - dox/user_guides/step/step.md Diff File
mod - dox/user_guides/visualization/visualization.md Diff File

Issue History

Date Modified Username Field Change
2018-05-27 13:47 abv New Issue
2018-05-27 13:47 abv Assigned To => ysn
2018-07-09 13:54 git Note Added: 0077393
2018-07-09 13:54 ysn Assigned To ysn => abv
2018-07-09 14:00 ysn Note Added: 0077394
2018-07-09 14:00 ysn Status new => resolved
2018-07-09 14:00 ysn Steps to Reproduce Updated
2018-07-12 18:16 abv Note Added: 0077548
2018-07-12 18:16 abv Assigned To abv => bugmaster
2018-07-12 18:16 abv Status resolved => reviewed
2018-07-12 18:43 bugmaster Status reviewed => tested
2018-07-14 12:26 bugmaster Changeset attached => occt master 07f2b741
2018-07-14 12:26 bugmaster Status tested => verified
2018-07-14 12:26 bugmaster Resolution open => fixed
2018-07-14 12:42 git Note Added: 0077616
2018-07-30 10:27 bugmaster Test case number => Not needed