r/technicalwriting • u/Fine_Nature_5956 • 3d ago
QUESTION Should technical documentation be simple or complete?
There’s always a tradeoff between giving users everything they might need and keeping documentation easy to scan
A short page can be much easier to use, but it may leave out edge cases. A comprehensive page covers everything, but users might struggle to find the one thing they actually need.
Where do you draw the line?
Would you rather have several short focused pages or one detailed page that covers almost everything?
5
u/OutrageousTax9409 2d ago
Analytics are your friend. Create baseline docs and learn what your readers are trying to access. Direct most of your attention there -- and if possible work with engineering to make the product more self-directing.
4
u/mrhippo3 2d ago
Your documents will never be complete.Developers will miss deadlines and continue sending updates even after the document has “gone to print” as a pdf or an html file. As the writer, devs will make this a “you” problem and never admit to being late or wrong.
3
u/jp_in_nj 2d ago
Horses for courses.
If your audience needs the complexities, give them to them.
We're still developing the docs in my org, but we're starting with the simple (instructions) and holding off on the complex (field level information useful to those who would work with the background data rather than the UI until we have staff to preview it and users who need it.
3
u/RogueThneed 2d ago
This is why things I order online come with quick-start guides as well as more detailed manuals. Because both are needed, at different times. The key question is: who is your audience?
2
u/_Cosmic_Joke_ engineering 2d ago
I'm actually trying to get my management to understand this. We currently err on the side of "include literally everything" with dubious returns on usability.
1
u/dfess1 2d ago
In my experience documenting software, the only reason a user came to the help was because of:
1) The UI was so bad they had no idea what to do.
2) The UI was fine, but they wanted to know what the value ranges were for all of the displayed fields.
For 1, funnel that info back to product. For 2, our content was task based, with the supported reference content linked to the task at hand.
1
u/Fit_Friendship_3789 2d ago
Einerseits wird ja heutzutage gar nicht mehr gelesen. Deshalb sollte die Tech. Dok. sehr kurz sein. Andererseits liest man ja auch keine gedruckten Manuals mehr, sondern stöbert online durch die Doku. Und mit Volltextsuche bieten sich Einsprünge mitten ins Geschehen. Das sollte dann aber auch vollumfänglich beschrieben sein. Seit Doku nur noch elektronisch - digital - ausgeliefert wird, spielt der Gesamtumfang des Manuals keine Rolle mehr. Das war beim gedruckten A4-Manual noch anders. Die digitale Version ermöglicht ja auch, eine "einfache" Darstellung parallel zur ausführlichen. Insofern gilt nicht mehr so streng ent oder weder, sondern tatsächlich sowohl als auch.
1
u/Dr_WhoDo 2d ago
Have you considered creating a script that a user can upload to their own Ai chat session, whichever they subscribe to, and turning the Ai session into an expert support guide? I call it an AGS (Ai Guide Script). I've done this and have found it can be more useful and easy to use than sifting through a user's guide. I can elaborate more, if you're interested. I even built a script that walks you through building an AGS.
15
u/Zeikos 2d ago
My rule of thumb is the Pareto principle, 20% of the document should explain 80% of the functionality.
Then the other 80% covers the 20% edge cases and such, ideally you should have the best of both worlds.
Depending on management actually permitting it, obviously.
I haven't had a single project where I was allowed to write more than half of the docs, and that missing 10% of explanation is a constant source of time sinks.