The term “user documentation” can mean many different types of work, ranging from documentation for end users who need help with the very basics to documentation for system administrators who are installing and configuring complex systems. The actual deliverables can include everything from quick reference guides and tutorials to configuration guides and support “knowledge base” articles. Technical communication is about much more than just user guides, books, and online help systems.

In my role as a senior technical writer, I have spent years writing documentation for all sorts of different users. For example:

• Installation, upgrade, and configuration guides that explained how to set up a large system with many different components. These documents were intended for system administrators who understood networks, database servers, and web servers. They needed to know how to integrate our systems with their existing back-end systems and how to fully configure our software.
• End user guides that explained how to use web-based client software and Microsoft Outlook integration to accomplish particular tasks. These users (typically attorneys and legal secretaries) had less computer knowledge and very little time to spend learning software. They needed help written in non-technical language and targeted to the particular tasks they wanted to accomplish.
• Documents intended to help support staff and trainers support the end users. In some cases, I created customizable guides covering basic procedures; customers could modify these to match their own configuration.
• Developer guides that covered our various APIs; see my API and Developer Documentation page for more on that topic.
• Articles and FAQ documents posted to a searchable support site to help users quickly find answers and troubleshoot problems.
• Patch release notes that documented the particular issues fixed in the patch, as well as installation instructions.

Why Your Product Needs Documentation

In today’s world, many software companies do not create large, printed manuals for their products, but that doesn’t mean that they don’t need documentation. Technical writing is all about explaining things, and almost all products need at least some explaining if you want your users and customers to get value from your product. That explaining can take many different forms — FAQ pages, knowledge base articles, quick reference guides, and so on.

Even mobile and web apps can benefit from lightweight documentation pointing out how to get the most value from the application. Users need to know how your product is going to help them accomplish particular tasks; the last thing you want is for a user to completely miss out on your product’s capabilities and walk away (perhaps leaving behind a bad review at the same time).

For example, in one project I worked on, we created a web-based app hosted in the cloud. This app communicated with a database installed in the customer’s own environment, behind their firewall, so it was a bit unusual for a mobile app. After analyzing the user needs for this product, I wrote two guides:

• A guide for the system administrators explaining how to install, configure, and troubleshoot a “connector” that would connect their system with the cloud-based system.
• A much more basic guide for the actual end users (typically attorneys) focused on quick descriptions of the user interface, the benefits of using the app, and frequently asked questions that highlighted areas the users were likely to misunderstand or miss. The guide included only a few step-by-step procedures, as the actual steps were very easy; the challenge was making sure that users knew what they could do in the app. Since the app handled sensitive data, I included a short section explaining how we handled security and how they could be sure that their data would be kept safe. All of this was written in straightforward, non-technical language.

My Documentation Approach

For all of my documentation projects, I have a very hands-on approach. I like to set up my own test environments and use the system, much the way the actual user would. While I always love having access to design specifications and requirements documents for background on the system, the hands-on approach is essential for authoritative and accurate documentation.

As a side-benefit, I often become an “honorary” QA and design team member during this process, finding and reporting bugs and usability issues.

I understand that developers are very busy when working on a new system and I respect their time. Before turning to a developer with questions, I always make sure that I’ve done as much research on my own as I reasonably can. The questions I bring to the development and engineering staff will never be “stupid questions.”

In any organization, I build good relationships with the product management, customer support, and quality assurance teams, as they are often a terrific source of knowledge about our customers.

It is not at all unusual for me to become an expert on the systems I document; by the time the project is done, people in customer support will often come to me with questions before seeking out other resources.

For the last eight years, I have done all my technical writing and user documentation work as a full-time remote employee. Working independently and effectively in this environment is second nature to me.

---

Does your company need a writer who will take a hands-on approach, learn all about your product and your users, work independently, and produce the right level of user documentation for your needs? Contact me.