|Subject:||Problems reading/writing technical documentation|
|Posted by:||Richard Owlett (rowle…@cloud85.net)|
|Date:||Fri, 01 Apr 2016|
I am new to a particular programming language. I have a problem
with one sentence in the "man page" describing a particular
function. In context, there is little dispute about what it
intends to mean.
The question is:
* Does it say it?
* Does it say it clearly?
* Does it say it grammatically?
A side question to clarity is it readily translatable. [I am
reminded of a story from the early days of computer translation.
The example was given of automatic translation from English to
Russian back to English of "The mind is willing but the flesh is
weak." The reported result was "The wine is good but the meat is
I will quote without context as the document in question aimed at
all levels of expertise and previous experience. The quotation is
the introduction of a particular example code fragment. It says:
"Add nothing at all to the variable x (often useful for checking
whether an argument to a procedure is actually integral and
generating an error if it is not):"
Comments please. I'm interested in comments in comments the
multi-lingual, especially non-native English speakers.