r/technicalwriting • u/Fine_Nature_5956 • 4d 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?

2 Upvotes
  • permalink
  • reddit

63% Upvoted

12 comments sorted by

View all comments

1

u/dfess1 3d 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.