To a blues pianist like myself, railroads mean one thing: Boogie Woogie, and with that the romance of the engine chugging across the twilit landscape, a moving island of warmth  in the midst of nature at its wildest, or industry at its bleakest.

So, its no surprise that I found myself fascinated by the DRail model railway layout software.

Model railway enthusiasts not only understand the romance of rail, they seek to recreate it in their attics or back bedrooms. It’s not a cheap hobby – all that well-engineered track and rolling stock  costs money. It’s also a little complicated, since you’ve got to persuade the whole lot to fit together.

You could just buy track and tinker, or plan it all on paper. However, it’s easier – and potentially cheaper, to get yourself a software package to enable you to do your trial-and-error on-screen, and on the cheap.

I dread to think what David had to go through to build DRail. Functionality aside, it has a library of accurately modelled track for all major manufacturers – something of an achievement in itself.

David – as you might guess from his URL - is Dutch. He wanted to make sure that his English website read well to native speakers, so he gave me a shout and I did my thing. I was overjoyed when he mailed me to say:

“…since I put up the website that you edited, I doubled my conversions for the English/American market.”

He then threw his draft documentation my way. I gave it a Full Edit, and he liked the result:

“I’m very happy with your work. I think it gives the product as a whole a quality boost!”

So, post title aside, neither of us has the blues about this project…

In an online help, illustrations are usually just a waste of screen real estate – the user already has the interface open! 

However, a web version of the your online help, complete with screenshots, can act as a walk-through for potential customers, and aid SEO. I pride myself on providing this at no extra cost.

Here some examples of my work:

• Audio Zone Trigger
• Averina Code Signing Library
• Direct Access
• Webcam Zone Trigger

Just sometimes a project lands on my desk and I get the feeling that I’m helping make a little IT history. The Averina Code Signing SDK was one of these:

Averina Code Signing Library provides an easy-to-use but powerful API for software publishers and application developers to programmatically sign and verify code files using Authenticode® technology. It also introduces Averina’s brand new technology, Universal Software Identification™, which provides improved authenticity for signed software products.

The mathematical underpinnings for this are frankly scary!

I delivered the documentation as both a self-contained .chm file, and HTML pages formatted to look like a traditional online help.

Fortunately my mathematically frayed nerves did not seem to affect the quality of my work. The client was kind enough to say:

You have a great talent to describe even the most technical subjects in a very simple and clear way. Our customers will definitely benefit from your contributions to our reference material. We are looking forward to work with you on our future projects.

Judge for yourself…

As I found with my first project for them, VisualHint documentation is high on technical content. I was therefore particularly pleased that Nicolas Cadilhac felt able to come back with Smart PropertyGrid.Net 2.1:

For the update of the documentation of Smart PropertyGrid.Net 2.1, I logically chose to do business with Documentation Doctor again. The initial document had been very welcome by my customers so it was an obvious choice to reiterate the process with a company that works well and quickly.

It’s validating when people come back for more!

In this case, Joe was happy with my work on his Zone Trigger documentation, so asked me to polish the Audio Zone Trigger manual. This entailed creating both a conventional HTML Help (.chm) and web-based help with pictures.

Jo was kind enough to mention me on a forum for independent software vendors:

I just had the documentation revamped for all my products by fellow OISV member Documentation Doctor. I just want to recommend his services to everyone here, this guy is in a league if his own, and a pleasure to work with.

Imagenomic make software for enhancing and modifying digital images.

This means that prolonged exposure to the images making up their documentation is almost guaranteed to induce psychedelic dreams!

Fortunately, the visual overload does not seem to have affected the quality of the resulting document:

Documentation Doctor took our assignment, which required absolute accuracy for a lengthy, image-intensive product tutorial, and turned it around promptly and with minimal need for additional input or adjustment. This doctor had the right remedy for a painful situation, and we are feeling better for it! I highly recommend the Documentation Doctor, and would not hesitate to use his affordable yet highly professional services again.

Are you shooting yourself in the foot with bullets?

Ever click on a radio button, only to get a popup window  or – worse – a crazily whirring C: drive and a sluggish progress bar? Annoying isn’t it? More importantly, you quickly learn to distrust the GUI.

Bullets in documentation are a bit like that.

The format of instructional text, like the design of a GUI control, can either succeed or fail to suggest its function. In other words, just like software, documentation can have good or bad affordances.

Bullets look like a non-ordered list…

Read the rest of this entry »

To be honest, this project scared me!

SmartPropertyGrid.Net is a cool, user-friendly, easy-to-deploy replacement for the Microsoft Property Grid, familiar from applications and programming environments. As a techwriter, I’m thrilled by the product – it locks out a lot of UI issues, and ensures consistent layout.

The snag is that, though I’ve done some coding in the past – and boast that I’m a wizard with VBA – I have no experience of .Net.

Thankfully, all Nicolas wanted was a Basic Edit. Though he communicates effectively in English, his first language is French. He needed somebody to make the manual read as if written by a native speaker, and to give the presentation a polish, for example turning paragraphs into numbered instructions.

From the outset, we agreed that this would only work if we acted like an in-house team…. though actually, it was a bit like playing that children’s game, “Battleships and Cruisers”.

Whenever I got stuck – which was often at first – I mailed Nicolas with two or three guesses. Sometimes one of my guesses was “on target”. Other times, I was so wrong it was funny!

Thankfully, my misunderstandings enabled Nicolas to supply new – clearer – draft copy which I could then edit. Mostly, we nailed queries in one iteration. However, there was one pesky paragraph which I think went to ten emails!

In the end, it was all worthwhile. Nicolas got the manual he needed, and was happy to say so in a public forum:

He just finished reviewing/fixing my 50+ pages Programmers’guide and the result is excellent with already positive feedback from my customers. I’m french and my doc was a poor word for word translation…

This was a fun project. Andrea has created a customisable shortcut tool for people who prefer keystrokes to mouse-clicks. 

My first reaction was “Good grief, this is retro!” I half-expected it to have a black-and-white DOS style command screen…

Of course, it turned out to be a modern, user-friendly application. It’s heaven for the command-line addict, and a natural choice for the trained typist. It’s also one of those products with all sorts of business uses. For example, the autotext function lets you handle dozens of similar, but unique, email interactions in record time, e.g. for operating a support desk.

I helped a bit with the press release and the website text. I’m also particularly proud of the animated .gif. Humour is not always a good idea in technical communication… but it has it’s place.

However, most of my work was on the manual itself, which I created as a HTML Help (.chm), and as a web-based help.

Andrea seems pleased with the results:

You offered exactly what I needed and I could not be more happy with the result.

I’m looking forward to his next release!