When providing documentation, there are almost always going to be a great many factors to consider. However, going back to a simple system of asking the “W5” will get you focused in the best direction.
Who – who is going to be reading this? Who is the documentation being focused on? Who did read it?
What – what is being documented? What does it do? What could it do? What might it best be used for?
Where – where should it be located? Not only where, in general, the documentation should be located but where updates and additions should be added to the existing documentation.
When – when will this documentation be read? When should the documentation be read? When was it read?
Why – why is the documentation necessary? There are several schools of thought on why something should be documented. However, in a perfect world, the documentation is only for those not using the service or product, to begin with, as the UX/UI itself should be designed in such a fashion that it is intuitive and self-explanatory. This may not always be the case, but we also don’t live in a perfect world.
Think of the analogy of sitting down to a bowl of soup with utensils. Granted, most people will understand the soup is food and can be eaten and choose to eat in a manner comfortable to themselves — they may pick up the bowl and drink from it, or they may use a spoon provided. Others may need to be “spoon-fed” as this is something new, and they are not certain how best to eat the soup… think of documentation as “spoon-feeding.”
Remember that too much documentation or documentation that is too complex may be seen as the equivalent of force-feeding another bowl of soup after the diner is full and satisfied with their meal. No matter how great the meal, there will always be a point where you need to stop eating.
Photo by Lightscape on Unsplash