Show
Being a technical writer has taught me a variety of industry skills, however I have discovered that there are a few key challenges I must overcome in order to write engaging and useful help documentation for our customers. Complexity of help documentationTrying to maintain balance between technical jargon and simple instruction is the one of the primary objectives of any technical writer. Technical writing must be technical, it’s in the name, but this is not necessarily how it needs to be portrayed to the end user. It is the technical writer’s duty to understand the subject matter in a way that they can relay this back to their audience. Often is the case that the audience is unknown and therefore must be assumed to include a broad range of users with varying levels of technical knowledge and background. Help documentation needs to be written in a way that is understandable for a wide spectrum of users yet communicates the technical details of the subject matter efficiently. Keep it specificDocumentation needs to be kept concise and specific if it is to make the biggest impact to a user’s experience of a product. It is unlikely that the first step for a new user is to examine the whole suite of documentation before they use a product, it is most common for a user to read the documentation if they have encountered an issue. When they have an issue, it is likely that they want to fix it quickly and therefore documentation must eliminate any uncertainty and ambiguity if the user is to have a happy experience. InvolvementI believe the most important aspect to improving performance as a technical writer is to become immersed and involved in the projects that you will be creating documentation for. As part of the Software Development team at Software Europe, becoming involved in the development process as early as possible provides a clearer definition of deliverables and how the user will interact with them. All of these factors put in to practice will help to ensure a happy customer base. Want more like this?Want more like this?Insight delivered to your inboxKeep up to date with our free email. Hand picked whitepapers and posts from our blog, as well as exclusive videos and webinar invitations keep our Users one step ahead. By clicking 'SIGN UP', you agree to our Terms of Use and Privacy Policy Other content you may be interested inCategoriesCategoriesCategoriesCategories
CategoriesYou may be quite happy with the label if you write test reports or standard operating procedures. But you can have a very different role and still sometimes need to write technical things: a design brief, an employee handbook or even guidance on how to use the new office photocopier. If your document is complex, and someone needs to be able to follow and act on it, then it’s technical writing. The fact that many people don’t realise that what they’re writing is technical may partly explain why so many of these types of documents fall short. Fortunately, those shortcomings tend to fall into just a few categories, and they’re easy to fix. So let’s look at some of the most common difficulties technical writers (and their readers) face – and how to fix them. 1. Messy structureMany technical documents confuse readers and fail to achieve their aims because they were not planned properly to begin with. This lack of planning means that documents, especially longer ones, end up structured in an illogical fashion. Things are hard to find in the text, sections don’t follow naturally from each other, cross-references are a mess, and so on. At best, this frustrates readers; at worst, it makes the document virtually unusable. How to fix it: 2. Too much jargonWho your readers are will inform the content and style of your text. So it’s important to keep them in mind throughout the writing process. If you’re writing something for specialist readers, some jargon and technical language is fine; it may even be essential. If you’re writing for a general audience or people who actually specialise in a different area, be careful – what’s familiar and self-evident to you may not be so to them. One manager who commissioned a technical-writing course from Emphasis described how different specialists may ‘talk different languages’. You need to ensure that nothing gets lost in translation. How to fix it: 3. Poor punctuationAll writers have a passing knowledge of the main set of punctuation marks. Very few, however, outside of professional authors and editors, have a thorough grasp of how each one works. The use of full stops and question marks is painless enough, but beyond that there is widespread difficulty with getting the details right. When exactly are commas required? Which dashes go where? When should you use hyphens? What’s going on with colons and semicolons? How to fix it: 4. InconsistencyTechnical writing should convey coherent ideas and trains of thought. Unfortunately, this doesn’t always happen. And that’s especially true when a document is written over a period of time, created by multiple authors, or updated piecemeal without due regard for overall consistency and readability. These circumstances are common and can result in choppiness in the document’s style, layout, tone, point of view, and so on. For example, the text may address readers as ‘you’ in one paragraph and as ‘designers’ in the next. The tone may switch abruptly from warm and chatty to scientific. This can be disconcerting, if not downright confusing. How to fix it: Create a company style guide and make sure all your writers have easy access to it and are encouraged to consult it. This will do wonders for the consistency of your documents, both internal and external. Ensure that the guide not only includes vocabulary items but also addresses things like readership, typography, company aims, and brand voice and identity. A style guide is a living document, so put a system in place for proposing and incorporating additions and revisions to it. 5. Too much abstractionPeople writing in a formal or semi-formal context often go overboard in an effort to make their prose sound proper and elevated. Their writing, as a result, can end up very abstract and noun-heavy. ‘The achievement of good performance’ may sound fancy, but it’s a mouthful compared to ‘performing well’, and it’s really no more impressive than the plain-language option. It’s also less clear. Abstractions like this are unnecessary and, as they accumulate, make your prose turgid, verbose, and tiring to read. They can also make it ambiguous: if you describe a system as having ‘enhanced functionality’, do you mean it has more functions or that it works better? How
to fix it: 6. Unclear antecedentsAn antecedent is a word, phrase, or clause referred to by another word, which is usually a pronoun like it, they, or who. For example, in ‘Observe the results and add these to a worksheet’, results is the antecedent of these. Ambiguity can occur when there is more than one possible antecedent. Take the following: ‘Trainees should mark their schedules in the notebooks provided, then in the group calendars. The manager is responsible for them.’ Whoever wrote this knew what the manager was responsible for, but readers may reasonably wonder if them referred to the trainees, the schedules, the notebooks, or the calendars. How to fix it: 7. Dense presentationTechnical writing can be very … technical. Unavoidably so. Applying plain language as much as possible will help, though you still probably won’t win awards for literature. But even allowing for its stylistic limitations, technical writing can be made much worse through poor presentation. Long, unbroken chunks of text, for example, are visually off-putting and hard to follow. They can make a reader’s brain shut down out of sheer effort and frustration. The prevalence of jargon and complex concepts add further cognitive loads, and it all adds up. How to fix
it: Parallelism can lend grace, polish, and clarity, and is a grammatical device worth attention and practice if you want to improve your writing. It can take various forms, but essentially it means using matching grammatical structures in words, phrases or clauses that should work in parallel. For example, consider the sentence: For breakfast we like eggs and to grill bacon. Here, eggs is a noun but to grill is a verb. Better to write: For breakfast we like eggs and bacon, or: For breakfast we like to fry eggs and grill bacon. It’s natural to struggle with technical writing, especially if you only do it from time to time. Producing something that reads effortlessly is a challenge. But thinking about and applying these seven straightforward tips will benefit your writing experience. Even more importantly, it will make everything a whole lot clearer – and life a lot easier – for your readers. Interested in improving your technical-writing skills? We can train you (or your team) in that. Image credit: ALPA PROD / Shutterstock What are the typical obstacles challenges a technical writer faces during information gathering?7 challenges in technical writing and how to overcome them. Lack of information about product users. ... . Gathering information from Subject Matter Experts. ... . Outdated or unsuitable tools. ... . Inconsistency in the documentation. ... . Disorganized structure. ... . Getting people to review your work.. What is a major challenge that technical writers have to contend with?A major challenge that many writers face is how they get and support the technical information they're communicating. Who you need to extract information from may vary wildly depending on your industry and/or product.
Which are common errors in technical writing?So let's look at some of the most common difficulties technical writers (and their readers) face – and how to fix them.. Messy structure. ... . Too much jargon. ... . Poor punctuation. ... . Inconsistency. ... . Too much abstraction. ... . Unclear antecedents. ... . Dense presentation.. What are some factors that may cause inefficient and ineffective technical writing?Let's look at seven factors that cause inefficient writing even when the content is technically accurate and the grammar is perfect:. Uninviting Appearance. ... . Inadequate Information. ... . Confusing Structure. ... . Irrelevant or Uninterpreted Information. ... . Unnecessary Jargon. ... . No Visual Aids when Readers needs them.. |