Three ways to improve your user experience.


I believe the most overlooked concept of technical writing is discoverability. It does not matter how accurate your documents are if your users cant discover them. I believe discoverability covers three important cross-sectional fields that technical writers should pay attention to:

  1. Search engine optimization
  2. Table of contents
  3. Relevant information

Search engine optimization:

Your search engine optimization (SEO) should allow your users to quickly google your documents. When constructing your documents think about different ways your users will discover this document. This includes titles, key words, metadata, links to other pages, and naming conventions in the URL. SEO matters to you, your users, and your organization. Spending some time learning how search engines work will improve hits to your pages.

For example, you might have a title “Gain access to your account”, but your users are searching for “How to login”. While both titles are technically accurate, your users will be unable to find this useful information.

Table of Contents:

The table of contents or toc is often overlooked but pertains to discoverability. How do you want your users to transverse your documents. The toc will act as a reference point to your users and its best if there is some logic to your table. Keep in mind that as your product grows in size, so will your toc. It is best to organize your toc with some forethought.

For example, ordering the toc alphabetically doesn’t give your users a good “Getting started” guide which is pertinent to most organizations. Consider how you want your users to approach the documentation.

Relevant information:

Perhaps this can be left unsaid, but I have seen some documentation in which the title does not describe the body of the documentation. Nothing is more frustrated to a user than spending hours (or in some cases minutes) hunting for relevant piece of information. I recommend short and concise sentences that will give your users exactly what they want.

For example, a “Frequently asked questions” section should actually contain frequently asked questions about your product or service; such as cost, limitations, and advantages. Partnering up with other people in your organization can help provide insight to such pages.

Writers spend a lot of time on the information they’re documenting without thinking about the end users who need access to that information. Spend some time brainstorming how your users will find your documents and all that great information can be shared.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store