DiscussionsIssue archiveOCCT:Documentation

Archived issue #0029817

Documentation - avoid excessive use of "please"

Open CASCADEOCCT:Documentationclosed4 public notes

Search issues

Description

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

Steps to reproduce

NA

Public activity

4 archived notes

Participants are labeled by their role within this record.

01Commenter 2
Branch [archived branch] has been created by Participant.

[revision removed]


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.
02Commenter 2
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.
03Commenter 3
Reviewed, please integrate
04Commenter 2
Branch [archived branch] has been deleted by Participant.

[revision removed]