Saturday, April 10, 2010

Reformulate to avoid misunderstandings

Some of the best advice on technical writing that I have ever read suggested the writer try to explain their ideas in more than one way, usually through the magical phrase in other words.

The technique works by introducing your topic in one writing style, vocabulary, point of view, abstraction level, etc. and then the following sentence conveys mostly the same information, but from a different angle, using synonyms, using more/less details and/or introducing requirements or consequences of the idea. (See how I did that?)

It may seem like it is adding superfluous redundancy, but it helps avoid ambiguity and the clever use of synonyms should help make your document easier to find by search engines.  Just be careful not to overuse the technique.  In other words, some ideas are simple enough that they do not need to be restated.

Thursday, April 08, 2010

Jamie Cansdale is my hero

Jamie Cansdale (of Mutant Design) is the author of TestDriven.Net, a Visual Studio add-in that "makes it easy to run unit tests" (and it certainly lives up to that description).  A simple, casual feature request sent by e-mail two days ago was followed by fabulous customer support that culminated today in a private build that fully implements the feature, even with our unusual environment at work.

Jamie's e-mails came in rapidly and always with offers for more help in getting me to better use his already-fantastic product.  I sometimes had trouble keeping up with him!  The conversation was to the point and I felt I was being treated as a very important customer, not just some [l]user who needs to be clued in to the basics of computers by some first tier customer support who gets paid minimum wage and doesn't care about their job.

Jamie and I iterated through 6 private builds first by e-mail and then by instant messaging to explore the requirements and smash all the bugs in the implementation so that TD.Net could fully support the DeploymentItemAttribute, just like MSTest, even when the files being referenced were marked as read-only due to the nature of the source control system in use.  I came out of this experience a very satisfied customer, as - even though I use the software as a student to write open-source software - I decided to put my money where my mouth is and purchased a professional license.

If you're still reading, what are you waiting for?  Go buy the product and/or go provide customer service so good that your users will write blog posts about it!