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