ICT & Computing in Education

View Original

The hazards of writing software manuals

See this content in the original post

Introduction

Please, not another software update!!

This is an update of an article I originally wrote and published in 2015.

The built-in occupational hazard

Writing software manuals or books, or even mini tutorials on how to do something in a particular program comes with a huge occupational hazard. The software providers don't owe you anything, and so there is nothing to stop them changing something fundamental after you've finished your writing.

A few years ago I took a book out of the library called "Squarespace 6 for Dummies" or something, and it had hardly been touched. Not surprising, given the fact that Squarespace 6 had been unceremoniously declared defunct, and superseded by version 7.

I also came across this description of a nightmare scenario in which the writer says his book on Squarespace 6 was just about to go to the printers when Squarespace 7 took over: My Squarespace 7 book.

How to avoid or minimise the hazards

What can you do to avoid such a situation? I think there are three solutions:

Get hired by the company that makes the software

This is easier said than done, obviously. However, I have had a few successes in this department. To be honest, I even surprised myself. In one case I phoned the company and asked to speak to the Managing Director. It was a small company, so that wasn’t too difficult. All I said to him was that I thought the software was great, but the manuals were rubbish, and would he like me to write them instead.

He didn’t take me up on that offer, but asked me instead if I could be able to write manuals for other software they sold. Thus I ended up writing several books about desktop publishing for the company.

I also got myself commissioned to write a manual about Windows 3 (this was some time ago). I did that in conjunction with a chap called David Dunford, who supplied the screenshots as I didn’t have good enough software to do that myself. The gallery below shows the covers and, in the case of the Windows manual, the inside copyright page (just to prove it was me what did it!).

Get in with the in-crowd

Somehow become part of the inner circle or favoured few of the company concerned. Whenever Microsoft brings out another version of Office, say, there is always a handful of books available more or less immediately about the new version. Unless those writers can polish off a book in a weekend, they must have been privy to developments from the outset. Again, not an easy thing to do.

Include the version number in the title

Write a book based on one particular version, and make it clear that's what you've done. With Squarespace, that wouldn't have done you any good because it's cloud-based, meaning that everyone on Squarespace 6 automatically got transferred to Squarespace 7, or so I believe. But with other products, bear in mind that not everyone upgrades when a new version comes out.

Concluding remarks

Perhaps the main lesson to be learnt is to write the manual and get it published as quickly as possible!


WRITE!, a newsletter for nonfiction writers. Click the word “WRITE!" below to find out more, grab a sample copy and to subscribe. It’s free!

WRITE!