From tech writing to UX-based UI design

Maja Engel talks about moving into UX and UI design using technical writing skills and a flare for graphics.

This article was published originally in Communicator. Communicator is the authoritative, award winning, journal for UK technical communicators. It is home to high quality, objective, and peer-reviewed features – current, relevant, and in-depth.

User Experience, or UX in short, is one of those concepts that has triggered a lot of interest lately, not only in software houses, but also in other industries. Everything now seems to revolve around design: cars, furniture, phones, televisions, and so on.

Was it always like this? And if it was not, what has changed? When we are looking to buy a new car, we generally want it to be attractive and shiny, we want it to be fast, easy to drive and park, eco-friendly and have low fuel consumption. But there is another factor that car producers have taken very seriously and it has everything to do with emotions: we also want the car to be comfortable, make little noise, play our favourite songs and have that “je ne sais quoi” that makes driving a wonderful experience. It is the same in software design: the product must be functional so that the user can solve problems with little effort. However, this is not enough anymore.

These days it also has to be aesthetically pleasing. Finally, all that should be gift-wrapped in a way that creates some positive emotions and satisfaction on the user’s behalf. This is what UX is all about.

A logical question then arises: isn’t it the same thing as UI Design? The answer is: not quite. UX and UI Design are among the most confused terms in software design.

They are both essential and are closely related, but UX is concerned with the overall user experience in interacting with a product, whereas UI Design refers to the “things” the user actually sees and interacts with. To quote Rahul Varshney, Co-creator of Foster.fm:

A UI without UX is like a painter slapping paint onto canvas without thought; while UX without UI is like the frame of a sculpture with no papier maché on it. A great product experience starts with UX followed by UI.

Clearly, this field of expertise seems quite distant from technical writing and you are probably wondering how I got there. In this article I will tell you how I used my knowledge as a technical writer and mixed it with my personal interests and skills to embark on a journey towards UX and UI design.

Technical writers are, basically, walking and talking encyclopaedias of their company’s software and know their way around it quite well. We technical writers know our users and understand what they want, and we are able to better visualise the process flows they will undertake to solve a problem.

How did it all start?

When I started as a technical writer in the company I work for the user guide of our main software was already there. Each chapter had been written by the developers who implemented the given features, and my job was to re-write everything to make it more consistent, flowing and user-friendly. The first thing I tried was to complete some tasks with our software exclusively by following the user guide. I failed miserably. At first, I thought it was the guide’s fault, but very soon as I started re-writing the procedure I realised it was not entirely so. The user interface just did not follow the procedures it was supposed to represent and consequently, the user guide was enormous and very hard to follow. Just to take one example: you had to jump from one area to another with no apparent logic, open dialogs from other dialogs, or click an almost infinite number of times just to complete a task. When writing, I was able to form a clear picture in my mind of what the steps of a task should look like, but unfortunately, I had to describe what was there and not what I thought would be more sensible.

To provide a little bit of background information, the software my company creates is used for the optimisation of engineering design, it is the first of its kind and probably the best in class. From its birth in 1999, the number of features and functions has grown exponentially to accommodate our clients’ requests and helped it stay at the top of the market. However, in recent years the balance has shifted. We have been slowly losing ground because, despite our users continuing to be happy with the functions we offer, our competitors’ software is apparently easier to use. In fact, over the years our development process was primarily feature-focused, with very little regard for usability or aesthetics. As far as UX and UI Design were concerned, no rules or guidelines existed. Feature planning turned directly into implementation. To sum it up, if it worked, it was fine. However, increased functionality does not necessarily mean improved usability, something that I discovered on my own and came to an obvious conclusion: if it is difficult to write about, it is difficult to use, and not just for me.

So, how did I actually go from noticing what was wrong with our UI to actually influencing changes on it? I am quite handy with Adobe Illustrator and Photoshop and have experience in graphic design, so the developers started asking me to draw icons and jot down mock-ups of how a new tool or interface component should look like. In my free time, driven to a certain extent by my natural curiosity and perseverance, I started studying articles and reading books, following different forums and discussions to discover the best ways how to do those things. Soon I took a step up and began putting forward ideas on how to improve existing design issues, which could be seamlessly accommodated in the Agile environment we work in. I started small, for example, “that button whould best fit there” or “this component would better suit the purpose of this tool than that component”, or “these functionalities should be close together because they are performed in a sequence”. I tried to provide a rational motivation for each suggestion and I used my own documentation as both inspiration and signpost. In practical terms, I re-wrote some very complex chapters and sections of the user manual following a logical flow of user actions and redesigned the interface accordingly. This initiative of mine triggered quite some interest.

Due to the slow-down of our software, our Chief Technical Officer was already thinking about making UX a priority in our software development process and asked me if I would be willing to cover usability and interface design. Out of all people in the company, many of whom probably more qualified than I am, why me? The reason is because I am the technical writer and we technical writers are, basically, walking and talking encyclopaedias of our software and know our way around it quite well. We know our users and understand what they want, and we are able to best visualise the process flows they will undertake to solve a problem.

Why are technical writer good candidates for becoming UX experts?

We know our audience and we know how to wear their shoes! Whatever the format of our documentation, we know who we are targeting – new users, advanced users, specialised users or the general public, and so forth – and based on this knowledge, we adapt the style and format of the materials we produce. We know how frustrating it can be not to be able to complete a task because the software is not telling you what to do next or where you got it wrong because we’ve been there. A good example of this is messages and warnings of various kinds. In user manuals, it is good practice to state what happens after performing an action, so the reader is fully aware of its consequences. Naturally, on an UI this statement is implicit but a clear error message in case something goes wrong or, for instance, a loading bar, are just some of the feedback elements that can keep the user updated all the time. Similarly, if you are writing instructions for a procedure, you know that less-experienced users might need additional explanations, which on the other hand might be a burden for an advanced user who is only looking for very specific information. In such cases, I increased the readability of complex documents by highlighting the essential information (for instance, the steps of a procedure) and hiding any additional information in collapsibles with visible titles, so that the users who need them can still find them, whereas users who don’t will not be distracted by their presence. This brings us to our second strength.

Technical writers are perceived as mere conveyors of information

We can see the bigger picture! The developers are often so concentrated on implementing features and keeping up with deadlines that they lose focus on what the tool is about and what goal it should accomplish. Even though we think all the time about consistency and structure, we are prone to the same mistake. You have a lot to say and you don’t want to deprive your reader of even the smallest detail. Unfortunately, this can easily lead to documents so dense with information that instead of being informative, they simply become overwhelming and confusing. In other words, our users end up not seeing the forest for the trees. To avoid losing focus, it is important to outline the flow of actions from the beginning to the end where a goal is reached, highlighting any branching points and optional actions, but keeping the latter in the background. Another possible solution is to constrain the content to reduce possible sources of distraction to a minimum and keep the reader’s attention on their goals. This quality of technical writers goes hand in hand with the next one.

To avoid losing focus, it is important to outline the flow of actions from the beginning to the end to reach a goal.

We know how to prioritise! Some elements in our documentation need to be more accessible and more visible than others are because they are more important, or are even essential for completing a user task. Cluttered manuals where everything seems flat and equally (un)important are as unusable as cluttered interfaces: if it takes users too much time and effort to find what they need, they will eventually give up or call your company’s support services. The main reason behind this problem is the “What the user cannot see, they will not use”. A good way to re-organise such documents (and interfaces) is to use different kinds of font styles and sizes, graphical elements, title, colours and element positioning and grouping to create a visual hierarchy. Keep in mind the Fitts’Law (it is easier to hit larger targets close by than smaller targets further away) and the closely related Hick’s Law (the more the possibilities, the longer the time for the completion of a task).

The relationship we have with the developers is the final key. The materials we produce are not just the result of our hard work, but also of our cooperation with the developers. If you are just a technical writer, you step onto the stage at the very end of the implementation process. You are perceived as a conveyor of information. However, if you are the one doing the UI design, your role extends from a passive recipient of information to an active contributor from the planning phase all the way through to testing. More specifically, in an Agile environment after the stakeholders have had their say and the developers decided how to implement the requested feature, it is my turn to make a mock-up transforming those written specifications in screens, buttons, dialogs, drop-downs and icons. I come into play once more to perform the UI review, which precedes the final testing before release. This actually makes your job as technical writer a lot easier because it enables you to plan the documentation way ahead and avoid surprise features that somehow appeared overnight. Even if you are part of the same process in multiple points with a different role, I see it as a great advantage for both technical writing and UI design.

What to do next?

Technical writers want to be as informative as possible and help users solve problems by reading our documentation. We are also aware of the fact that very few people actually read our manuals, which calls for alternative help methods such as contextual help.

The first step in changing the design process to include UX is to define short and long-term goals, or in other words, make a detailed list of desired features and improvements and organise them in a timeline according to the benefits they yield for the users and level of difficulty for implementation. This is a very long, repetitive and tiresome process that should include all stakeholders, from project managers and developers to customers, but once you have organised the bulk of the work, the rest is quite straightforward. Concerning customers, I don’t really mean that you need to bring them to your company. Instead, you should have some written feedback from them in the form of surveys or, preferably, qualitative usability studies. These take some time to prepare and perfect, but they can bring you enormous long-term benefits.

As the first short-term goal, the project manager and the team decided to revamp the software look and feel without touching the functionalities and the logic behind the tools and wizards. Not an entirely usability-based decision, but the cost of this decision in terms of labour intensity was much lower than revolutionising how the software works, and its impact on the user was deemed to be rather high, especially in terms of attracting new users. For my part, I did some research on different kinds of software, both from our specialised category and general purpose software, and made a few proposals to my superiors. We decided to adopt the general Windows 10 look and feel with a limited number of colours, no shadings and no gradients: very squared, flat and clean. Once this decision had been taken I could begin redesigning the single components.

First UX design attempts

Just like content in technical writing, interface design also requires a style guide, although of a slightly different kind. How do you make components if you don’t have any guidelines on what they should look like? After quite a lot of reading, a few experiments and some simple arithmetic, I adopted a set of proportions based on the major-third scale and on a determined size of particular font type. In this way I achieved a set of sizes “for all occasions”, meaning that I could use them to standardise any padding, margin and size of any (even the most trivial) element without disrupting the visual harmony of the interface (or the part of it where the element is placed). Now came the hard part: test drawing all possible interface elements and controls and their combinations to decide which size fits best in which place, so once the new components are designed, the developers are free to code away to their heart’s content without thinking of whether a dialog is too airy or a label too small.

Consultations with stakeholders identified the toolbar as one of the “pain points” and as a result, it became a priority. Currently, our toolbar is made up of 16-pixel icons with no descriptions (only tooltips), all placed in sequence one after another, six textual menus and a right-click menu. All possible actions, whether compulsory, useful or entirely marginal, were dispersed among these three components and jumbled up together with no apparent logic and no prioritisation. Considering that our software has three almost independent environments, some heavy re-organisation was called for. I mapped all actions and labelled them according to the environment in which they were used or “general” if shared by all three environments. I placed all general actions in a single textual menu called “File” and assigned the rest to the toolbar, which became contextual to each environment. I took the actions assigned to each toolbar, grouped them according to similarities and relevance between them and ordered them in the toolbar according to their importance and frequency of use. I labelled all actions and used bigger icons for the most important ones. The first mock-up looked pretty good. However, I soon realised that I had fallen into an obvious trap: I wanted to include everything, so I had excluded nothing. In other words, the new toolbar was as cluttered as the old one. Pretty and flashy? Yes, but almost as confusing. This required a big spring cleaning. They were still there but if you wanted to use them, they were one or two clicks further away than before. On the bright side, important functionalities finally stood out.

Naturally, the new look and feel required new icons. The time finally came to say goodbye to the colourful and vintage 90s look they gave to our software. Lucky for me, we decided to eradicate the past developers’ habit of “over-iconisation” and I was able to eliminate many icons that added no meaning whatsoever, but only contributed to overall confusion. In the style guide, I specified the icon general style, together with some useful re-sizing instructions.

The last example I would like to briefly describe is something very dear to us technical writers. We want to be as informative as possible and help users solve at least those problems that can be solved by reading our documentation. We are also very much aware of the fact that very few people actually read our manuals, which calls for alternative help methods such as contextual help. By giving all actions dedicated text labels, tooltips repeating the same information became superfluous, so we expanded their function to include a brief definition of what the action is and a link to the specific section of the user manual containing the explanation on how to use it. Furthermore, we plan to create a component directly embedded in the interface that would enable users to search the help topics directly from the software and even access the relevant tutorials. This component should naturally be as un-invasive as possible, as it only provides an added value, but is not essential for all users. Our hope is that until we can actually take the UX of our software to the next level, the least we can do is make the necessary instructions and information readily and easily available.

Conclusion

Learning about UX and UI design has given my job an entirely new outlook. Don’t get me wrong, I love writing but being able to do something about the things I am writing about has been a source of enormous satisfaction and it has helped me forge an even stronger bond with the software developers. At this stage, a component design undergoes frequent changes as different ideas and customer requests pop-up and there is plenty of room for improvement. It is an ongoing work, not done by a single person but in a group: advice and feedback from different disciplines and areas of expertise are always welcome and, I would say even essential for getting the best results. In fact, UX goes beyond giving customers what they want and putting some makeup on it. To quote Don Norman, the cognitive scientist who coined the term UX: “Next comes simplicity and elegance that produce products that are a joy to own, a joy to use.”

Additional menu

How did it all start?

Why are technical writer good candidates for becoming UX experts?

What to do next?

First UX design attempts

Conclusion

Further reading

Footer