UX Writing: The Ultimate Guide To User-Friendly Copy
02/15/2019 Usability
Do you write user manuals or technical documentation? Do you often hear people emphasizing the importance of their user-friendliness?
But you hear it so often, that you actually do not know where to start looking for information about how to do user-friendly technical writing yourself?
UX writing in technical documentation is getting more and more important. Also, the user experience of products' instructions is considered as an important part of the customer journey.
In this guide/post, I have created a complete overview of all the topics to think of, when writing user-friendly copy.
UX Writing: the 8 main topics towards user-friendly copy
1. How to write copy for your audience
It is important that information on your product is communicated to the user accurately and effectively. Each group of users has its own characteristics, and it’s important to take account of these before starting the technical writing.
A seasoned end-user of an emergency-call system has different requirements from someone who’s installing modular pontoon systems. The following links will provide you with more insights into your audience.
Links about this topic:
- Aurora Bedford, 2015, Personas Make Users Memorable for Product Team Members
- Goltz, Shlomo, August 2014, A Closer Look At Personas: What They Are And How They Work (Part 1), smashingmagazine
- Hornsby, Peter, April 2015, Writing is design too, uxmatters.com
- Jahgirdar, Niranjan, October 2018, Using Personas During Design and Documentation, uxmatters.com
- Lehrner-Mayer, Karina, July 2016, Five tips for creating documentation that focuses on the user, tcworld e-magazine
- McMurrey, David, Audience Analysis-Just who are these guys?, prismnet.com
- Using a Style Guide for Technical Writing to Improve the Quality of Your Content
- Marx, Sophia, April 2016, Creating successful information experience for users
- Nielsen, Jakob, 1994, Goal Composition: Extending Task Analysis to Predict Things People May Want to Do
- Nielsen. Jakob, 2015, Use Specialized Language for Specialized Audiences
- Redish, J. C., 1993, Understanding readers, In C. Barnum and S. Carliner (Eds.), Techniques for Technical Communicators, Macmillan, 14-41.
- Task analysis, Usability.net
Technical writing books on this topic:
2. How to write UI copy that really solves problems
Because users want to get things done and because they do make mistakes while performing tasks, a predominance of troubleshooting information in operating or maintenance manuals is recommended.
The main rule here is first to help users avoid making mistakes by using short and simple sentences, signalling action information clearly and minimizing jargon. Furthermore, to master error-handling, it is recommended to help the user recognize there is an error (detection) understand what happened (diagnosis) and how to recover (recovery).
The following links will provide you more insights in writing clear error recognition and troubleshooting information.
Links about this topic:
- Dalvi, Meghashri, 20 February 2007, Effective User Assistance Design: Ten Best Practices
- Davis, Nicki, 11 February 2014, Business-Value Metrics for Field Studies, uxmatters.com
- Horsnby, Peter, 17 January 2011, Book review: The Design of Design: Essays from a Computer Scientist, uxmatters.com
- Keller, Laura, 22 June 2015, Designing Great Customer Services, uxmatters.com
- Meij, Hans van der, Minimalist principle 1: Choose an action-oriented approach
- Meij, Hans van der, Minimalist principle 2: Anchor the tool in the task domain
- Meij, Hans van der, Minimalist principle 3: Support error recognition and recovery
- Problem-solving review
- Redish, J. C., 2013, Letting Go of the Words -- Writing Great Copy, Confab London
- Writing user-friendly knowledge base articles
Technical writing books about this topic:
- Johnson-Eilola, J. and Selber, S.A., 2013, Solving Problems in Technical Communication
- Letting Go of the Words - Janice (Ginny) Redish (2012)
- Redish, J. C., 2012, Writing Web Content that Works, UxLx 2012, Lisbon
3. How to write structured copy with clear texts
Once you’ve gathered and selected all your task-oriented information, you can use it to start the technical writing and produce your texts. While you are doing this, it’s crucial that you keep your target audience in mind the whole time: they have to find what you’re communicating easy to understand.
In general, even the product information that is already there has to be edited. Marketing materials mostly are not accurate enough and technical descriptions not readily enough understood by, the target audience.
Quite often there is no written information at all. The following links will provide you more insights in writing technical documentation for your audience.
Links about this topic:
- Weber, Jean Hollis, May 2011, Developing a Departmental Style Guide
- Huffman, Cindy, 19 October 2015. Working on a User-Interface Text Team: A Case Study, uxmatters.com
- IEEE Professional Communication Society, Plain language
- Meij, Hans van der, Minimalism
- Meyer, Kate, August 2016, The Impact of Tone of Voice on Users
- Meyer, Katem July 2016, The Four Dimensions of Tone of Voice
- Plainlanguagenetwork.com, What is plain language?
- Samuels, Jacquie, May 2013, Getting Started with Topic-Based Writing
- Stellar, Martin, 9 December 2013. 5 Copywriting Tips That Can Dramatically Improve Your UX, uxmatters.com
- Stephanie Saylor, Why words matter
- Unwalla, Mike, Plain Language in Plain English: a review
- Vermeulen, Ferry, 2013, Eine Anleitung erstellen in 10 Schritten
- Vermeulen, Ferry, 2016, Simplified Technical English (STE): How to write clearer texts with STE
- Vizard, Linn, May 2016, Tell It To Me Straight – Plain Language in UX
- The IEC/IEEE 82079-1:2019 for Information for Use
Books on this topic:
4. How to use illustrations in your copy
Illustrations help make the steps you’re showing a lot clearer than is possible with words alone. Instructions for assembly and installation can often be replaced in their entirety by images.
What’s more, illustrations make for a visually appealing manual that is more pleasant to read. The following links will provide you more insights in creating clear illustrations in technical writing.
Links about this topic:
- Gabriel-Petit, Pabini, 23 January 2006, Color Theory for Digital Displays: A Quick Reference: Part 1, uxmatters.com
- Gabriel-Petit, Pabini, 23 January 2006, Color Theory for Digital Displays: A Quick Reference: Part 2, uxmatters.com
- Gabriel-Petit, Pabini, 20 January 2007, Applying Color Theory to Digitak Displays, uxmatters.com
- Haramundanis, Katherine, 1991, The Art of Technical Documentation, chapter 5: Graphics in technical documentation
- Hulitschke, Stefan, November 2013, The technical illustrator: A new picture, tcworld e-magazine
- Professional and Technical Writing/Design/Illustrations, Photo’s and illustrations, Wikibooks
- Solidworks Composer
- Vashishtha, Samartha, February 2013, Picture Perfect: Using illustrations in technical communications, IEEE Professional Communication Society
5. How to use multimedia to increase the UX
Using multimedia is a great way to effectively convey information on your product or service to your target audience. Different mediums can help you hold their attention for longer, and that means they retain what you’re telling them for a longer time.
In addition, research shows that users find it enjoyable to get their knowledge audiovisually. The following links will you provide you more insights in using multimedia for your user manual.
Links about this topic:
- Bryn Mawr College, 2021 - Technical Documentation
- Camtasia
- Food and Agriculture Organization of the United Nations, 2011, E-learning methodologies - A guide for designing and developing e-learning courses
- Hoober, Steven, 11 July 2016, Flatly Authentic - Mobile Matters, uxmatters.com
- Meij, H. van der and Meij, J. van der, March 2016, The effects of reviews in video tutorials (paper)
- Peters, Dorian, 24 July 2012. UX for Learning: Design Guidelines for the Learner Experience, uxmatters.com
- Six, Janet M., 14 June 2016. Lean UX for Wearables: An INterview with Greg Nudelman, Part 1, uxmatters.com
6. How to translate for increased UX
Technical documents often have to be translated: products that are traded internationally have to come with manuals that are easily understandable. By setting the technical-translation process up well directly after the technical writing, you can ensure the quality of the technical
translations, improve the UX and cut translation costs.
The following links will provide you with more insights into user-centred translations.
Links about this topic:
- Byrne, J., 2006, Technical Translation, chapter 5: Usability-strategy for translations
- Hoober, Steven, 4 January 2016. Practical Empathy for the rest of the world, uxmatters.com
- Rodriguez, Ania, 8 February 2016. How to Create a Globally Appealing User Experience, uxmatters.com
- Six, Janet M., 20 August 2012. Thinking Globally, uxmatters.com
- Suojanen, T., Koskinen, K. and Tuominen, T., 2015, User-centred translations
- Wright, Sue Allen and Budin, Gerhard, Handbook of Terminology Management
7. How to support successful access to information
It is generally acknowledged that end users don’t read the manual from cover to cover and that they more often prefer to consult the information they need online.
To overcome these issue, information developers would first of all be well advised to stick to a defined terminology and to develop a meaningful Table of Contents and an index. Secondly, product information should be distributed using several platforms/mediums, like a print manual, online (for all devices) or on the device.
The following links will provide you with more insights into giving the user access to information.
Links about this topic:
- Albers, Michael J, 2012, Human-Information Interaction and Technical Communication
- Bailie, Rahel, September 2010, How to create useful FAQ pages. Content Marketing
Institute - Ganguly, A. and Chaudhuri, S. 8 August 2016. Accessible Documentation, uxmatters.com
- Hollis Weber, Jean, 1992, Hints for developing a table of contents
- Jose, Maria, January 2016, Designing the perfect table of contents
- Meij, H. van der, Minimalism principle 4: support successful information access
- Newton, Ben, 20 April 2015. Website Accessibility: The Untapped Global Income Stream
- Quesenberry, Whitney, 20 December 2010. Accessibility First - for a Better User Experience, uxmatters.com
- Techscribe, 2004, Indexing technical documents
8. User Feedback: user research and staying in contact with your users
Getting feedback and staying in contact with your customers is one of the most valuable assets a company can develop. Improving on them is a great way to increase the customer lifetime value (CLV).
By keeping in touch with your customers you can collect meaningful feedback for documentation, technical writing improvement and product development. Analytic data, such as topic views, search keywords, used search terms (also terms that yield no results), can provide very valuable insight into how your users use your documentation and product and how it can be improved.
The following links will provide you with more insights into how to stay in contact with your users.
Links about this topic:
- Julien, Jordan, 22 October 2012, The Importance of Knowing User Intent, uxmatters.com
- Lehrner-Mayer, Karina, July 2016, Five tips for creating documentation that focuses on the user, tcworld e-magazine
- Madcap Pulse
- Madrigal, D. and McClain, B. 3 September 2012. Strengths and Weaknesses of Quantitative and Qualitative Research, uxmatters.com
- Madrigal, D. and McClain, B. 5 December 2011. Planning User Research Throughout the Development Cycle, uxmatters.com
- Nielsen, Jakob, March 2016, Getting Users to a Specific Feature in a Usability Test
- Ross, Jim, 7 March 2016. Excuses, Excuses! Why Companies Don't Conduct User Research, uxmatters.com
- Veal, Raven, August 2016, How To Conduct User Experience Research Like A Professional
- Wadsworth, Martha, 7 tools to stay in close contact with your user
Books on this topic:
Other useful technical writing resources:
- Ganier, Franck, Comparative user-focused evaluation of user guides: a case study
- Ultimate CE-Marking Guide
- Johnson, Tom, 10 strategies for user-centred documentation
- Nielsen, Jakob, June 2016, Using the Title Attribute to Help Users Predict Where They Are Going
- Nielsen, Jakob, 2014, User Experience Career Advice: How to Learn UX and Get a Job
- Redish, J. C., 2010, Technical Communication and Usability: Intertwined Strands and Mutual Influences, IEEE Transactions on Professional Communication, 53 (3), September, 191-201. (PDF, 332 Kb)
- Redish, J. C., 2010, Writing Vibrant, Compelling Content, User Interface Engineering - Virtual Seminar, September (webinar)
- Steehouder, M., Jansen, C., Poort, P. van der and Verheijen, R., 1994, Quality of technical documentation
- Theofanos, M. F. and Redish, J. C., 2005, Helping Low-vision and Other Users with Web Sites That Meet Their Needs: Is One Site for All Feasible? Technical Communication, 52 (1), February, 9-20.
- Vermeulen, Ferry, 2016, Technical Writing Tools: The Ultimate Expert Choice
- Vermeulen, Ferry, The Declaration of Conformity and How to Draw Up One (Inc. 27 Downloads)
Technical writing links:
- plainlanguage.gov
- usability.gov
- awwwards.com
- 52weeksofux.com
- smashingmagazine.com
- usabilitypost.com
- blog.uxpin.com
- idratherbewriting.com
- urbinaconsulting.com
- https://fivesketches.com
- 101 Technical Writing Examples
With help from and many thanks to:
- Marie-Louise Flacke
- Hans van der Meij
- Rahel Anne Bailie
- Janet M. Six
DO YOU WANT TO KNOW HOW YOU CAN CREATE A COMPLIANT USER MANUAL FOR THE EU?
A step-by-step approach to developing compliant user instructions and avoid legal pitfalls.