Making technical documents interesting...

Technical write-ups can be boring if they talk just technical stuff. But some writers make an attempt to make them interesting.

Like in the Java API reference. Here's an example. In explaining the difference between the append() and insert() methods in the class StringBuffer, this is what I found in the API reference.

The principal operations on a StringBuffer are the append and insert methods. [...] The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point.

For example, if z refers to a string buffer object whose current contents are "start", then the method call z.append("le") would cause the string buffer to contain "startle", whereas z.insert(4, "le") would alter the string buffer to contain "starlet".

It wasn't really necessary to pick an example where all three words made sense. But someone went that extra step.

Little things - and it made it just that little interesting.