Writing Help Documentation for New and Veteran Users

One of the challenges facing documentation writers since the beginning of software is the following dilemma: how to reconcile help content for first time users and veteran users? The working assumption being that first time users need to be taken by the hand and led throughout the product step-by-step, whereas veteran users are versed in the product and need to learn only advanced and new features.


Mark Baker, a long time technical communicator and content engineer, wrote extensively about this matter. He argues that users are no longer at the level of novice-ness that requires hand-holding documentation, and that software UI has improved to the point where users are protected from disaster by intelligent microcopy and careful UX.


We have the power to run sophisticated interfaces. Early electronics did not have the power to run fancy interfaces, to provide infinite levels of undo or to warn about any destructive actions before executing them. Interfaces used to be cryptic and dangerous because they ran on limited hardware. Now they are clear and safe because we have the computing power to make them clear and safe.

Mark Baker, Tech Comm’s Obsession with Novices has to Stop


He is right about the fact that software in general has become less intimidating and more accessible to lay users. Seemingly, help documentation is needed less and less, since product building adheres to user-centric design principles. This is the kind of design that supposedly allow  users to “figure out how to use an app just by looking at it”. 


Only that ideal can’t apply to complex interfaces that require some mastery. In fact, it doesn’t even apply to super-simple interfaces like gmail, when new features are rolled out. Help documentation will always be needed, it is merely a question of making it (like we do products) more accessible to all.


How to address two different audiences at the same time?

That leaves us with the new/veteran users question: how can we write help documentation so that it speaks to new and experienced users at the same time?


While usability barriers between users and software have been reduced considerably, we would still be amiss to stop differentiating first time users from advanced users. Only now they are no longer defined by sheer access to software, but by the level of their engagement with the software.


Advanced users are comfortable with and seek out more advanced features. And therein lies the answer – help documentation should cover the full scope of features a product has to offer. This way users can seek out help items they need, regardless of whether they are considered advanced or not.


writing for advanced and new users stock photo

Advanced users seek help, too.


Another important principle in writing help content is to keep in mind that you never really know who you’re writing for. To paraphrase Mr. Baker’s blog name – “every feature is feature one”. It’s safer to assume that any given feature is the first feature a user has stumbled on. Novice users landing on advanced features will soon navigate away from them, but at least they will find their way to help that is more appropriate for their level, instead of becoming frustrated and giving up on the software.


Guidelines for ensuring all user levels get the right help

1. Connecting items internally, in a way that always leads back to basic features – introductory features, onboarding tutorials, etc. This can be done easily through inline suggestions like “Note sure what this term means? Read more on this ABC article”.


2. Maintain consistency in referring to terms. It helps users orient themselves and learn the product’s terminology.


3. Offer access to onboarding tutorials at all times, from everywhere in the knowledge base. When users become frustrated from failing at a certain feature – help will be near. That will help reduce the likelyhood that they’ll give up altogether.

Noa is Iridize's Head of Content. With a background in digital strategy planning and database management, Noa translates Iridize's vision, stories and data into words. Digital learning and user experience are a particular passion of hers.