One of the ways that companies are cutting costs is cutting out the position of technical writer with the tasks being added onto the role of the UX person. Here is how I have managed the technical writing aspects of the projects I have been on.
First and foremost, make sure all of the copy is in one place. There is no way to expect developers and QA to hunt through the wireframe to check all the different messages, text, emails, and errors which have been written. It also makes it a lot easier when you are auditing the finished product against wireframes. I usually try to track this document in the same code tracking software as the developers but if that is not an option then find a way to keep different versions as the software and wireframes get changed.
The document is a basic table, split up into each of the areas or paths the user will take. Make sure that all the screens fit in somewhere. The headers for the table are:
- Message reference number: Helps reference the same message as the text changes. It also makes it possible to line up with the user flow.
- Message Version: If you are not using tracking software developers need to know if they have the latest message.
- Message Type: error, email, message, button
- App State: Where will this message be found in the process or what is the trigger causing the error message.
- Message intent: This helps you have the right state of mind when writing and editing the message, it helps developers, and if they bring in someone else later it helps with documentation.
- Message Title: or email subject.
- Message Content: The full statement so the developers can copy and paste.
What to write?
For starters, make sure it is written at an 8th grade level. (Year 9 for European countries.) There is a good chance the text being written could be highly technical but reducing the need to think helps smart people just as much as it helps others. Google has an advanced search item to check words for reading level if you are unsure (http://www.google.com/advanced_search).
The most important tip I can give when writing messages: if there are any variables or filler content in the message add a lot of x’s. (e.g. XXXXX Server Name XXXXX, or XXXX Details here XXXX) It is an easy thing that can be searched for to make sure it does not end up in the final product. “Lorum ipsom” is made to look like real text and does not get noticed as easily so could make an embarrassing addition to a website. While on the subject of filler text. It might be funny, but I wouldn’t recommend putting temporary messages which insult the company, co-workers, users, the product, or use profanity (unless of course it is part of the brand). It seems obvious but there is no reason to loose your job if something does slip out.
The three parts of a message are:
- What went wrong. If there is room you can say why, but usually the user does not care.
- What the user needs to do. This is often left out. Even if all they can do is “go back to the start”; giving them an action makes it so the user does not have to think.
- Options to choose from. The buttons should be action words. For example a button saying delete is easier to understand then a button saying OK. Also, if there can be a cancel or back button included, it should be added. It satisfies the heuristic of allowing the user to undo mistakes.
What not to write:
- Avoid jargon if possible. (Give definitions if it is unavoidable and there is a lot of jargon)
- Keep the messages short.
- How short? All messages also need to be distinguishable from each other.
- Don’t forget the Alt text for images associated message. (description of action if on a button)
- If the software will be internationalized, only have full statements since trying to split up a sentence into smaller pieces doesn’t work depending on the language. If the statement is split up it can be parsed wrong and lead to weird results
- Don’t apologize, saying sorry makes the user angry.
- Only use please if the verb is vague. Saying please in every message will make it loose its meaning.
- Include articles before the noun (e.g. remove the disk, not remove disk.) It helps the user know it is a physical object.
- Don’t use (s) to pluralize words, it is confusing.
- Don’t use click here. It is vague.
Finally, how to check what was written
When writing, your brain know what was intended and will fill in typos and fix bad wording. To get your brain to think it is approaching new text change what you are reading by switching font typefaces, color, font size. You can also print it out and read it as a different format. My personal favorite is to have the computer read it back to me. Both Mac and Windows have text-to-speech.
This is just an overview. It will not make you a technical writer, but with UX designers getting assigned everything, it might help you keep from looking embarrassed. The wording checklist I created might also be helpful.
Credits:
Some pictures are from: What happens when placeholder text doesn’t get replaced
Wording checklist based on: https://developercenter.vmware.com/web/standards/-/terminology-and-word-choice
Recent Comments