Take the 2-minute tour ×
English Language & Usage Stack Exchange is a question and answer site for linguists, etymologists, and serious English language enthusiasts. It's 100% free, no registration required.

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

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:

[http://golang.org/doc/articles/laws_of_reflection.html]

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.

share|improve this question
    
Exclusive disjunction is what it is, of course? –  Kris Jun 14 '13 at 15:08
    
@Kris, yes, but I'm looking for a language where this idea of an exclusive disjunction is a first-class type. –  three-cups Jun 14 '13 at 19:31

4 Answers 4

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

:-)

share|improve this answer
    
Not a bad idea, but I'm not sure I'd like to learn a new language by reading REs. REs are notoriously hard to read and comprehend. –  three-cups Jun 14 '13 at 14:47
    
@three-cups You may have overlooked the smiley\. –  MετάEd Jun 14 '13 at 14:48
    
Ahh! :) Thanks! –  three-cups Jun 14 '13 at 14:56

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.

share|improve this answer
    
Thanks, @Mitch. I've read a lot of technical documentation over my career (I say this not to assert authority or some special knowledge, but just to say that I have a lot of experience with it). I've also had to write a lot of technical documentation. I've always found english to be inexact when trying to share precise details, especially when describing computer programming. I find myself wanting to write code in my documentation to describe exactly what I'm trying to say. –  three-cups Jun 14 '13 at 14:53
    
There is some place for abbreviation in the manner you describe. In more narrative style writing, the term 'respectively' is often used so as to elide all the identical stuff in the parallel sentence. –  Mitch Jun 14 '13 at 15:00

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.

share|improve this answer
    
I absolutely agree. –  three-cups Jun 14 '13 at 21:48

I found an interesting "language" (discussed on Slate's Lexicon Valley podcast) called loglan (http://en.wikipedia.org/wiki/Loglan). This may be what I was looking for.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.