Wednesday, 21 October 2015

Is there a language or subset of English for technical writing

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.

No comments:

Post a Comment