Technical Writing - Keeping It Honest

The only thing you have to lose in your career as a technical writer is your credibility. All the hard work of building a portfolio and developing your client list is for nothing if you, or worse still your clients, get caught making claims that aren't justified.

User documentation is not just about supporting a product; it's also about selling it. There's yet to be a piece of software introduced in any organisation without some resistance to it. When people buy the latest technology, they want to be delighted by it but they often remain sceptical until they can see improvements in their lives, and so on.

As an author of any kind, you owe it to your audience to deliver the truth. Even if that truth is not as palatable as it might be, there's no hiding a problem forever and if you confront it properly in your documentation then there's no need to be embarrassed about it either.

Check Your Facts

Just because it's written down, it doesn't mean that it's necessarily true. I could claim, on my website, to be the world's number one designer of gadgets for cars but a quick Google search would quickly prove me wrong.

You can fool some of the people, some of the time. Respected journalists have skimped on research and lifted "joke" articles from sources such as Wikipedia and printed them as fact. They all get caught, and you will do to.

If your client tells you that their product is the cheapest in the world, find out whether that's the case. If it's the fastest - get the test results that prove it. And so on.

Wiki is a great resource for guiding your research but it should never be treated as fact, without gaining supporting information from a wide range of credible sources.

Find a Work Around

If there's something not so hot about the product, don't mask it, don't cover it up. Confront it and supply the most practical work around. Almost every software system ever released has issues that are discovered after testing, or were missed out of initial requirements capture and won't be available until a future release cycle. Recognising that fact and letting users know there is an interim solution (however inefficient it may be) is better than burying your head in the sand.

People often trust the written word implicitly; they believe what they see in newspapers, they see authors of books as experts and use the Internet to answer almost any question. Which is why they feel most betrayed when they find out they've been mislead, don't fall into this trap - work with your clients to keep your writing honest and they'll be very happy with the results.

Nick is the President of [http://www.authoring4u.com] a specialist consultancy based in Shenzhen China, which helps companies from around the world save time and money in the areas of; technical documentation, Internet presence and marketing and Press Relations.

The only thing you have to lose in your career as a technical writer is your credibility. All the hard work of building a portfolio and developing your client list is for nothing if you, or worse still your clients, get caught making claims that aren't justified.

User documentation is not just about supporting a product; it's also about selling it. There's yet to be a piece of software introduced in any organisation without some resistance to it. When people buy the latest technology, they want to be delighted by it but they often remain sceptical until they can see improvements in their lives, and so on.

As an author of any kind, you owe it to your audience to deliver the truth. Even if that truth is not as palatable as it might be, there's no hiding a problem forever and if you confront it properly in your documentation then there's no need to be embarrassed about it either.

Check Your Facts

Just because it's written down, it doesn't mean that it's necessarily true. I could claim, on my website, to be the world's number one designer of gadgets for cars but a quick Google search would quickly prove me wrong.

You can fool some of the people, some of the time. Respected journalists have skimped on research and lifted "joke" articles from sources such as Wikipedia and printed them as fact. They all get caught, and you will do to.

If your client tells you that their product is the cheapest in the world, find out whether that's the case. If it's the fastest - get the test results that prove it. And so on.

Wiki is a great resource for guiding your research but it should never be treated as fact, without gaining supporting information from a wide range of credible sources.

Find a Work Around

If there's something not so hot about the product, don't mask it, don't cover it up. Confront it and supply the most practical work around. Almost every software system ever released has issues that are discovered after testing, or were missed out of initial requirements capture and won't be available until a future release cycle. Recognising that fact and letting users know there is an interim solution (however inefficient it may be) is better than burying your head in the sand.

People often trust the written word implicitly; they believe what they see in newspapers, they see authors of books as experts and use the Internet to answer almost any question. Which is why they feel most betrayed when they find out they've been mislead, don't fall into this trap - work with your clients to keep your writing honest and they'll be very happy with the results.

Nick is the President of [http://www.authoring4u.com] a specialist consultancy based in Shenzhen China, which helps companies from around the world save time and money in the areas of; technical documentation, Internet presence and marketing and Press Relations.