Is there a language or subset of English for technical writing?

Question

I read a lot of technical documentation, especially in the computer programming space. Today I was reading the following paragraph in The Go Blog: The Laws of Reflection:

Any type that implements a Read (or Write) method with this signature is said to implement io.Reader (or io.Writer). For the purposes of this discussion, that means that a variable of type io.Reader can hold any value whose type has a Read method

This paragraph could be re-written like this:

Any type that implements a Read method with this signature is said to implement io.Reader. Also, any type that implements a Write method with this signature is said to implement io.Writer. For the purposes of this discussion, that means that a variable of type io.Reader can hold any value whose type has a Read method

I'm guessing the first paragraph was used instead of something like the second because the second (my) example is longer.

This all got me thinking, "It'd be great if there were a way to write this paragraph that is clear and concise". Something like:

Any type that implements a [Read|Write] method with this signature is said to implement io.[Reader|Writer]. For the purposes of this discussion, that means that a variable of type io.[Reader|Writer] can hold any value whose type has a [Read|Write] method:

In my example above, one could imagine the square brackets allowing for a choice of words with the options separated by a pipe.

Before going down the road of thinking more about what a language like this may look like, I'm wondering if this has already been done? I.e. is there a language or writing style that addresses these concerns? ("These concerns" being how to be clear and concise in technical writing.)

One specific issue I'd like to address is have a construct for xor.

---

I found an interesting "language" (discussed on Slate's Lexicon Valley podcast) called Loglan. This may be what I was looking for.

Answer 1

Of course there is a language which addresses your concerns! In technical writing, use regular expressions to identify sets of related sentences that you want to express clearly and concisely. For example, the regular expression

Any type that implements a (Read|Write) method with this signature is said to implement io\.\g-1\. For the purposes of this discussion, that means that a variable of type io\.\g-1 can hold any value whose type has a \g-1 method\.

clearly and concisely identifies the following two sentences:

1. Any type that implements a Read method with this signature is said to implement io.Read. For the purposes of this discussion, that means that a variable of type io.Read can hold any value whose type has a Read method.

2. Any type that implements a Write method with this signature is said to implement io.Write. For the purposes of this discussion, that means that a variable of type io.Write can hold any value whose type has a Write method.

Or, even more clearly and concisely:

Any type that (implement)s (a (Read|Write) method) with this signature is said to \g-3 io\.\g-1\. For the purposes of this discussion, that means that a variable of type io\.\g-1 can hold any value whose type has \g-2\.

References

“Regular expression”, Wikipedia
“Perl regular expressions”, perldoc.perl.org
“Source of the famous ‘Now you have two problems’ quote”, Jeffrey Friedl’s Blog

:-)

Answer 2

The only answer for this is 'yes' but that doesn't tell you what you want.

One way to get this is by osmosis: read lots of technical things and try to imitate their style. This is not particularly translatable to others, but is how many people learn how to do it. This is not restricted to technical writing but can work for any style.

Another method, which works specifically for technical language, (academic, legal, medical, engineering, building, technical instructions) is to emphasize strict meanings of words and strict patterns of sentences and to follow stipulated (explicitly authoritatively required) rule.

But what you are asking for I think is actual explicit guidelines on how to write technically. There are numerous guides (books, on-line advice) on how to do this well.

Answer 3

In addition to brevity, which you mentioned as a reason for preferring the first version of your example to the second, there is another advantage, namely that the first version makes it immediately obvious that the statements about "Read" and about "Write" are exactly parallel. In the second version, one can see the exact parallelism by comparing the first two statements word for word (and "Also" also helps), but after doing the comparison I might have a nagging feeling that I overlooked some subtle difference between the two. That nagging feeling would be worse in the case of longer blocks of text. So I would be inclined to write your first example, perhaps with "respectively" in place of "or". Alternatively, I might write the whole story about "read" and then write "The same goes for 'Write' and 'Writer' in place of 'Read' and 'Reader'." The main point is that I would want to avoid repeating large blocks of text with only very minor changes, partly because of the resulting excess length but mainly because it's better for the reader to be told explicitly what is being changed and what is unchanged.