Technical Writing Basics: All in One Place
by Bradley Nice, Content Manager at ClickHelp.com — software documentation tool
Technical writing is not easy. It demands a set of particular skills and specific knowledge. If you are on your way becoming a technical writer, the following compilation of useful articles might be of great help for you.
Some people like to write creative content or poetries. Others like to explain to people how products or software works. If you are particularly talented when it comes to breaking down complex processes into easy-to-understand articles, then technical writing might be the right niche for you.
So, you’re considering a career in technical writing. Maybe we’re a bit biased, but that’s an excellent choice. It’s a gratifying job, though not without challenges…
Technical writing has been around for a few centuries. Throughout the centuries, technical writers served as mediators between people, who created technology and people who used technology. But where does technical writing come from? How old is it?
What makes a good tech writer? This profession only seems easy and straightforward. There are many hidden rocks in being a technical writer, and, as for being a good one — there’s even more.
Technical writing doesn’t come without its fair share of challenges. For an outsider, creating user documentation may seem like a straightforward job: you receive the project details, analyze the task, and then just start writing.
If you are interested in becoming a technical writer or you’d like to keep yourself updated on the recent news in the field, the following blogs may be of help.
Some writers dream of creating the next Harry Potter or Catcher in the Rye. Some hope that their plays will be turned into the next Pulp Fiction. And, others find joy in explaining how things work and helping others to perform certain tasks…
You may have seen this job title popping on professional platforms or in your network, only to ask yourself: what exactly does a technical writer do?
What is user documentation for a company? We know what it is for end users — a place where they can get acquainted with product functionality, get their questions answered and generally find out more about the product…
Do technical writers need some special tools to produce such a complex product? Sure! Some tools they can buy, and some they already have. Using them right is what matters. Let’s see what those tools are.
Sometimes, you just open a user manual and know that it is bad. It doesn’t look sloppy, it has a lot of material, the hard work of the documentation team can be seen through the lines. And, it is still bad. How did this happen? This, my friends, is an example of a documentation team falling the victim to disobeying the almighty 80/20 rule…
Technical documentation is not just any text. It is a whole new world with its rules and patterns to follow. This article will explain how technical writers can avoid the most common mistakes when writing a user manual.
To jargon, or not to jargon: that is the question. Although technical writing and the word ‘jargon’ appeared long before Shakespeare, this is not exactly the famous question posed by Hamlet. Today it is a tricky matter which occupies the minds of specialists in technical communication and all sorts of writing. But first of all what is jargon?
What do we want from any user manual? Clarity and consistency. And, good looks. How can we achieve this? Well, as far as looks are concerned, you can start off by reading this article on user documentation design.
Some user guides capitalize each word within a title, some leave out the preposition, and others go for the classic: capitalize the first word and the proper nouns. The problem is that, there are a lot of articles out there that focus on capitalization from a grammatical standpoint, but when it comes to technical writing, the information is rather lacking.
Hyphenation is a linguistic phenomenon which is quite often left out of grammar books. Nevertheless, there are rules that one must follow to use hyphens right.
There are several pages in the English grammar that will make you keep coming back to Google for help. The use of the Possessive Case (especially with proper nouns) is one of those tough guys.
If you are a native English speaker then the choice between Active Voice and Passive Voice is likely to be obvious to you. But, if you are writing user guides in English or working in an English speaking team while it is not your mother tongue — you should study the vital difference between these two voices.
Find out how to befriend the wild beast — a page layout. Note that this post mostly applies to printed manuals, although, some things mentioned here will work for both — online and offline user guides.
It is hard to imagine now that people will be ever going back to living thier lives without the Internet. Being offline will soon disappear as a concept. The IOT is about to burst, and this will finally settle ‘being online’ as equal to ‘being alive’.
What matters more: text or images? The short answer is — both are crucial. What makes the difference between user documentation that engages and one that falls flat is striking the right balance between the two.
It’s time to talk about workflow optimization, and what you can do to make sure your team can do its job correctly.
You must avoid falling into one of these two traps: micromanaging the entire user documentation process or failing to supervise your team properly. This article will teach you how to avoid getting caught in either one of those scenarios.
Most of the times, the documentation team is kept isolated from the other teams, although cross communication and collaboration are vital to fulfill an assignment adequately…
Becoming part of a documentation team can be a challenge for a writer who is not experienced in this type of work, as it requires a new set of skills and a very specific writing style and approach. Even if you recruit a writer with prior experience in creating documentation and user guides, you still have to develop a smooth and efficient onboarding process to help them adapt to your organization as quickly as possible.
Think about it this way: Most people look for online help whenever they don’t understand how a product or service works. If you can help them solve their problem, then they are more likely to make a purchase…
There are several ways companies can go to handle their user guides. Some companies have documentation teams of their own, others manage to keep documentation running by involving support engineers, devs and QA into the technical writing process. There’s yet another way: outsourcing.
PDF and Word are on the list of the most used text formats. The dominance of Microsoft Word files is explainable — Microsoft Office is the king of desktop text editors for Windows users.
Have a nice day!
Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors