Lots of good advice on writing short technical papers. I preach many of the points specific to the writing per se but I’m terrible about effectively using graphics to complement the writing and make it enticing to read.

Writing is a tough business because writing takes so much more effort than reading, but the written word has distinct advantages over the spoken word: 1. it scales: you can address a large audience without gathering them all in one room (podcasts admittedly can also accomplish that) 2. it’s fast: people read 2-3 times faster than they can listen 3. it can be easily searched or versioned.

…

A good paper is like “Shrek”

…

Another pet peeve of mine is the usage of the word “this” as a stand-alone reference. As programmers we understand the dangers of dangling pointers and NPE’s, but many seem not to apply the same rigor to writing.

h/t Rich Main

Writing for Busy People - Enterprise Integration Patterns

Ed Bailey May 01, 2015 11:39

A good article.  I can certainly see the value in incorporating graphics, but the visual aspect is much more difficult for this wordsmith (as can be demonstrated by some horrific disk partition graphics in Red Hat Linux documentation of an age.) ;-)

Imported from Google+ — content and formatting may not be reliable