Writing for User Experience (UX)

Writing for User Experience (UX)

Figure 1. The concept of writing for User Experience (UX).

Module content

This module contains the following;

  • What is user experience (UX)?
  • Why is UX important for technical writing?
  • What are UX principles?
  • How to write user-friendly technical documentation.

User experience, otherwise known as UX, is used to describe the emotional sentiment of an individual when they use a product. This product can be of any form - physical or digital.

It is also the sum of techniques employed by design and developer teams to make a product easy to use by the target audience.

UX is concerned with how the user (the reader in this context) can use the product according to its functionalities to fulfill their tasks, how well they understand its unique capabilities, and whether they have an overall pleasant experience.

There are common misconceptions attached to writing for user experience. This module will discuss them to clarify doubts with detailed explanations.

The first is this:: user experience (UX) and user interface (UI) are the same.

User experience (UX) is often and wrongly interchanged with the user interface (UI). Although both concepts complement each other, they have different components and, therefore, can not be used in place of one another.

The user interface (UI) is the part of the product where the user can see, touch, and interact.

The second is this: writing for user experience and UX writing are the same.

This is untrue; here’s why. Writing for user experience is aimed at creating content that improves the usability of products for users, while UX writing is the written aspect of user interface design.

User satisfaction in technical writing

Figure 2. Understanding user satisfaction in technical writing.

It involves crafting words, phrases, and sentences to fit a user interface. It is meant to make text clear, readable, concise, and user-friendly.

These concepts, user interface (UI), user experience (UX), and writing for user experience have one goal in common: user satisfaction.

Now that you understand the meaning of user experience, let us learn why it is important for technical writing.

Why is UX important for technical writing?

Technical writing involves creating specialized content to convey information about a product to its prospective and continuous users.

Technical writing can be found in virtually every field, from medicine, telecommunication, sports, and media to software development.

Technical writers are adequately trained to curate content with the key terms of each field they specialize in.


The role of a technical writer can be likened to the function of a bridge. This person connectsvthe user and the product.

If the content created by the technical writer concerning a product does not explain all of its features, the user might not use the product properly.

It also takes away the anticipated consumer satisfaction and reduces their productivity.

Judging from the sensitive position of a technical writer, it is important to prepare written content so that users can understand and adequately describe the product’s features. This is where writing for user experience comes in.

Writing for user experience is applying UX principles when curating written content. For instance, most software development tools and frameworks have steep learning curves and can be tasking, even for users with knowledge of similar products.

The technical writer’s role is to ensure they apply all the UX principles necessary while creating clear and concise documentation for users.

What are these UX Principles?

As with UX design, UX principles are a set of instructions that designers use to create products for users with the aim of ease of use and positive experiences.

There are a lot of UX principles, and this module will discuss them in the context of technical writing.

These are some UX principles.


This is a means of designing products users can access despite their disabilities.In technical writing, this means that written content should be made accessible for all readers, despite their disabilities.

It is not advisable to assume all product users are free from neurological and physical impairments.

Writing for accessibility can be achieved by splitting large paragraphs and adding diagrams and charts. Alternative texts should be included in images for description. Link texts should carry meaningful information.

Audio content in form of transcripts can be added at the top of content pages. Captions should be added to enhance multimedia identification.


As with popular brands, they can be associated with a particular slogan or color. A particular thing comes to mind whenever you hear or think of that brand. This is possible because the brand has created associated traits for themselves.


For example, Docker has the image of a whale carrying a stack of containers on its way to customers, closely related to their services. This can be found on their website, blog, documentation and social media pages. This way, whenever a reader sees their logo, their mind instantly thinks of Docker.

Consistency is maintaining the language, feel, and look of written content for a product across different marketing channels, on the website, blog, and official documentation.

It can be achieved by maintaining using a style guide. An ideal publication or company has a unique style guide that tells its technical writers how to construct their official documentation and other related documents.

This covers all aspects of written content, from grammar and composition, use of pronouns, addition of backlinks, SEO optimization, and others. A style guide prevents a disruption in the flow of content transmission, especially with the change of writers. A popular example of one is Google’s writing style guide.


As it sounds, the usability of a product is ranked on how easy users find it to use. In technical writing, it refers to written content that can be understood and implemented by all product users, old and new.

Usability can be achieved by testing already written content on brand-new users and noting their reactions and the rate of their learning curves. It can also be improved by conducting anonymous surveys, correcting loopholes, and permitting open-source contributions for users.


Hierarchy is the methodical arrangement of written content to suit an acceptable narrative. We know that when we pick up a book, the first word or phrase we expect to see is the title, followed by the author’s name.

After that, the table of contents follows, then the main content/body of the content. Technical writing is a vast space as it covers proposals, white papers, tutorials, SDKs, and API documentation, all of which have different approaches.

The technical writer can achieve hierarchy with written content by writing it according to its requirements or outline.


For example, if you were to write a tutorial, you would write a title, add a cover image and prerequisites needed by the reader, and then the main body of the tutorial, assisted by visual aids to ensure they are on the right track.

The writer would add headings and sub-headings as needed (from h1-h5), bullet points, numerical or alphabetical lists for key points, and adequate paragraph spacing to make the content easy to read.


This is an important principle that cuts across different sectors aside from technical writing. By creating documentation within context, users have access to specific information related to the concepts of a particular product.


If a product caters to users with macOS and iOS devices and gadgets, writing troubleshooting guides and user guides that include Android and Linux-based devices may not be useful to the users.


This is the ease at which a specific piece of information can be found in written content so that users can easily find what they want using a search bar or keywords.

Findability can be achieved by implementing hierarchy and information architecture to aid ease of use. Headings segment the content and make in-content searches easy to carry out.

Check your knowledge:

Question 1:

______ is the sum of techniques design and developer teams use to make products easy for consumers to use.

Question 2:

Which of these is not an element of typographical emphasis?

Up next: writing user-friendly technical documentation!

How to Write User-Friendly Technical Documentation

There are several ways to create user-friendly documentation. These steps are as follows:

Know Your Audience

Know your audience before creating content

Figure 3. Know your audience before creating content.

Before creating content for users, it is important to research the background of the users. For example, tutorials for new users would differ from those curated for existing product users.

Tutorials for new users can be tagged “beginner guides”, such as “a beginner’s guide to creating Kubernetes clusters”, “everything you need to know about using headless CMS platforms”,“how to migrate from x to y as a newbie”, and similar titles.

As they are named, they should provide detailed information, carefully explain concepts, and name all the prerequisites for the user to follow the tutorial properly.

Existing users with some experience with the product in question would not need to be coddled so much. Explaining concepts they are familiar with would only bore them, but adding prerequisites, visual aids, and aids for troubleshooting issues is still necessary.

It is necessary to apply tact when choosing how to write for your audience, as a single misstep can cause user dissatisfaction. This eludes the aim of catering towards a positive user experience.

Implement Information Architecture

Implement information architecture

Figure 4. Implement information architecture while creating technical written content.

Information architecture is the process of organizing written content for ease of use and navigation. It can be implemented by making optimal use of white space.

This prevents the content from looking clumped and bulky. Readers often lose interest in written content when it looks bulky, as it plants a notion they would not finish.

Also, with the advent of information being delivered at very short intervals, lengthy sentences and paragraphs tend to receive less positive treatment. Arrange your content accordingly in a manner that permits easy navigation. An easy way to do this is to create an outline and use it as a framework for the final result.

This outline can then be split into a main heading, the title, and sub-headings for new points. Use lists (alphabetical lettering, bullet points, numbers, and Roman numerals) for information breakdown.

It is necessary to arrange your content properly to aid your reader’s search for specific bits of information. It also helps them to follow step-by-step instructions without needing clarification.

Use Consistent Formatting

Use consistent formatting while creating written content

Figure 5. Make use of consistent formatting.

Use consistent formatting while writing. Do not mismatch the arrangement of written content while writing. For example, using images of different sizes and dimensions in the same piece could be less visually appealing and tends to put the reader off balance.

Using a variety of listings is not recommended as well. If you start the article with alphabetical lettering, stick to it. If you prefer numbers, stick to that also. Mixing them up makes your work look unarranged, giving off this unco-ordinated feeling.

Use a particular font, and only use elements of typographical emphasis like capitalization, bold, italics, backtick, code blocks, and strikethrough where necessary, as these are used to draw attention to a particular word or phrase.

Where writing style guides are given, adhere to all its instructions and the minute details included. Maintaining consistent formatting while curating written content is important as it gives off a professional outlook.

Use Plain Language

Use plain language while creating written content

Figure 6. Make use of plain language.

Technical writing means something other than that the content would be filled with technical jargon and hard-to-read sentences. Write in plain text and avoid using technical terms unless necessary.

Where technical terms are needed, explain them or relate them to familiar words. Use examples to break down complex concepts so readers can fully grasp them.

Do not use vague, unfamiliar words. Do not use ambiguous text. Do not use trendy words or terms associated with only a particular region.

Do not use offensive language, indigenous language, or broken language. Use editing tools to brush up on your grammar and composition skills if they need to be improved.

Interactive Elements

Make use of interactive elements while writing

Figure 7. Make use of interactive elements.

These can include GIFs, memes (only when allowed), short videos, and simulations embedded in the content for further elaboration.

These will help readers assimilate faster and visualize without being taught physically.

Adding frequently asked questions (FAQs), hyperlinks, and information from other official sources can also help readers get an unbiased view of a product and its competitors.

This can aid a product’s market standing, as users can compare and contrast products with similar features.

Note that these elements should only be used in the content context. Anything other than that would be considered a distraction and look out of place.

User Feedback and Content Update

User feedback and content update

Figure 8. Make use of user feedback and content update.

Leave room for comments so the readers can talk about the content. This will help the writer know if their work had a positive impact.

Most companies have a “Was this page helpful?” button, which users can click to indicate whether the content fulfilled its purpose.


For example, BMC documentation has a detailed explanation of how to create an avenue for readers to provide feedback and how to view feedback for written content. Read more about it here.

This will also aid in implementing needed corrections. Users can contribute to the content through open-source contributions.

Products will not remain the same for a long time. Their features can be updated to suit modern trends, and the product needs to be updated.

It is necessary to replace outdated information with current information throughout the product’s lifetime. This will prevent a steep learning curve for users and promote ease of use.


For example, medusajs, a headless CMS e-commerce platform, was formerly known as an open-source alternative to Shopify. At the start of 2023, this descriptive title was changed, and now they are known as an open-source platform, providing digital blocks for digital commerce.

Any form of written content bearing the former description: an open-source alternative to Shopify is clearly outdated and counts as spreading misinformation to readers.

Why is Writing for User Experience (UX) Important in Technical Writing?

Writing for user experience (UX) is an essential skill for technical writers. Writing aims to ensure users enjoy a product’s capabilities and derive a positive experience while using it.

This module explained the meaning of user experience and highlighted popular misconceptions about it. It further discussed why user experience is important for technical writing and the UX principles writers can apply.

Writing user-friendly documentation is no mean feat, but as with every skill, it can be learned. Applying the methods taught will be sure to give you positive results.



Complete the following exercises before leaving this module.

Write an article on Caisy, a headless CMS platform. Introduce it to users and highlight the features that set it apart from other CMS platforms.

Your article should be between 1,500-2,000 words. Make use of the Google writing style guide, ensure to implement all the UX principles taught in this module, and make sure your content is user-friendly, according to what you have been taught.

Publish the article on Hashnode, share the link on Twitter and LinkedIn. Tag @caisyio and @TechnicalWriti6 on X (Twitter) with the link to your published submission.

Answer the following questions.