Technical Writing - It's harder than you think

Blog about technical writing and why it’s so hard. Of course there will be spelling & grammar mistakes in it….

NOTE: By writing about writing, I realise of course I’m opening myself up to everyone finding every possible spulling and grammatical mistake, and making me fully aware of it. Thanks, no really.

I was having an interesting conversation with a Technical Director of a large IT department in the Public Sector recently about solutions documentation. I.e. technical documentation provided for by vendors & partner companies.

His opinion was far from complimentary.

I found this fascinating, and it set me thinking. Personally, the ability to write and document technical subjects has been a massive benefit to me throughout my career, and it’s gotten me noticed. It’s aided my career progression right from those early days. An ability to document and present your ideas aligned to your target audience is a valuable skill, and one I believe is thoroughly worth the time investment. I’m often asked to present technical & complex infrastructure designs & requirements specifically because of time spent investing in learning in how to present such things.

Technical writing is far harder than a lot of people imagine. The Internet of course gives easy access to a whole range of technical writing styles and abilities, and I’ve done nothing but learn from other people’s work. People such as Alex Lewis and Justin Morris are two technical writers that I personally have a lot of time for. They seem to have the ability to present complex ideas in a very simplistic and procedural way - a rare skill in the technical community, and one that I’m sure they’d agree has been beneficial to their chosen career path.

The main complaint on the solutions documentation was around the purpose and fitness for purpose of the documentation. The term ‘screenshot monkey’ was used – took me a while to work that out. Essentially the opinion was that a list of screen shots showing how an implementation is configured is not adequate solutions documentation.

After thinking about this for a while, I realized I completely agreed. To understand why, you need to think about what solutions documentation is actually for. To qualify, I’m talking from the perspective of documentation provided by a vendor or provider to an end client.

So what is the documentation for? Well, it’s key to remember that if a vendor or partner has been engaged on certain technologies, it’s likely that the client does not have adequate skills or resource in that technology area to implement in-house. This is an incredibly important point, and one that’s most relevant to the ‘screen-shot monkeys’ comment.

Knowing that there are not strong skills in-house, the solutions documentation generally has to meet some core purposes, including:

  • Assistance with fault finding during support/service issues.
  • Qualification of dependencies on other areas in the systems.

There are secondary uses of course, such as hardware/software usage tracking etc. but the above two points stand clear as key delivery points for technical documentation - it not only explains what is implemented, but why and how.

Screen-shot based documentation does not readily help fault resolution. Often, returning settings to what they were ‘by documentation’ does not readily solve any issues, and certainly not where documentation updates through change control have been lacking.

You can often return a system to exactly the same settings from every screen shot you can find, and the system in question will still not operate in the way originally intended.

This shows a distinct issue with this type of documentation – and that gap/issue is around purpose.

It’s all very well having screen shots of settings and configurations, but if the purpose of those settings are not understood then there’s not much real value in those screen-shots.

If you can understand what the purpose of particular configurations are, it’s possible to gain an insight into what the system is doing, and how. A far more valuable piece of documentation than a screen-shot dump.

The technical staff that I’ve come into contact with that follow this ‘screen shot’ approach also tend to follow a hardware view of the world upward. That is they’ll document from the server level up through the operating system, and then the application layer.

I think that’s a mistake. When I do solutions documentation I tend to start from the Application layer downward – completely opposite. I also focus specifically on the service the solution is delivering, how it’s delivering it, and what kind of issues would arise if this particular configuration component was wrong.

The documentation is focused on the overall purpose of the infrastructure downward, not from the core components upward. I believe that to be a significant difference.

This leads me on to another comment that was made – this was centered on people’s actual real ability to write. The point was made that documentation containing poor grammar, spelling & structure undermined the value of the documentation. It’s almost as if it undermines the trust in the technical author’s skills. It’s an interesting point, and while I’m not totally convinced of it in all situations, I do have some sympathy for it.

For the documentation/proposals etc. that go through my hands I can be an absolute stickler for grammar & structure. If something is hard to read, people won’t read it, and if they won’t read it, they really won’t understand your message. That’s not a good place to be.

I don’t think I’d
go as far as this guy who states that he won’t employ anyone who makes grammatical mistakes, but I think I vaguely understand their point!

Technical writing is hard, but it’s worth the investment time to be good at it.
blog comments powered by Disqus