I’ve recently started writing help documentation, too, and I have…feelings.
There’s a balancing act between copy that shows up in the UI and copy that lives in the help center. What lives where? Should you give as much info as possible in the former, or go for minimalism and dump it all in the latter?
I’ve heard writers, designers, and PMs advocate for both. And it’s tricky, because there’s no overarching answer that works 100% of the time. But there are some guidelines that can help make that decision.
Usability
Assume your user isn’t ever going to click on that Learn more link or open up the help center. Can they still accomplish what they came to do? The answer should be yes.
Of course there will be occasions where the user needs extra info to know they’re doing the right thing. You can’t always plan for every contingency. But if a string of text will only be useful for 1% of 1% of users…chances are that can be left out of the UI.
Readability
Look, minimalism is a tenant of good UX for a reason. A lot of info on the page is overwhelming; the more there, the less likely the user will read what they need to know.
I say this carefully, because sometimes this principle is taken too far. Important info shouldn’t be left off just because it takes up a bit more of the white space than we wanted. (PS — the reverse is true, too. Please don’t add a line of copy just to fill in some gaps. That helps no one.)
So: give the user what they need, but do your best to not overwhelm. Or underwhelm. Just…whelm them.
Accessibility
How often will your users access the page you’re designing? If it’s a dashboard, probably often. If it’s onboarding, probably once. And is the setup ongoing or final?
Some information needs to be accessibly all the time, not just once. A dashboard with complex calculations can have a one-line explanation in the UI, but provide the precise formula in the help article.
Good writing is about presenting information at the right time and the right place.
Comprehensibility
Does your product exist for experts or newbies? It matters. Is your average user going to understand the terminology and lingo, or will they need to be walked through the basics?
In a perfect world, copy would work for both. It would be understandable for the beginner but not too detailed for the pro. This is the balance we should strive for, but often we have to make compromises.
A good rule of thumb is to explain terms the first (and maybe second) time users see it; afterwards, it’s safe to assume they understand. But help documentation is a great place to direct users if they want to dive deeper into the space.
In a nutshell
Focus on context. What does the user need to know right here and right now? What might they find useful later? What questions may they have? Am I overwhelming them with info, or holding back too much?
Wherever it lives, copy should be relevant.
Comments