MantisBT
Mantis Bug Tracker Workflow

View Issue Details Jump to Notes ] Related Changesets ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0029817Open CASCADE[OCCT] OCCT:Documentationpublic2018-05-27 13:472018-07-30 10:27
Reporterabv 
Assigned Tobugmaster 
PrioritynormalSeverityminor 
StatusverifiedResolutionfixed 
PlatformOSOS Version
Product Version 
Target Version[OCCT] 7.4.0*Fixed in Version 
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
Attached Files

- Relationships

-  Notes
(0077393)
git (administrator)
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 (developer)
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 (manager)
2018-07-12 18:16

Reviewed, please integrate
(0077616)
git (administrator)
2018-07-14 12:42

Branch CR29817 has been deleted by inv.

SHA-1: b93ddf5104997586921e70244f001b936d04801f

- Related Changesets
occt: master 07f2b741
Timestamp: 2018-07-09 10:53:01
Author: ysn
Committer: bugmaster
Details ] Diff ]
0029817: Documentation - avoid excessive use of "please"

"Please" is now used in the documentation only in sensitive cases.
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 View Revisions
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


Copyright © 2000 - 2018 MantisBT Team
Powered by Mantis Bugtracker