In general terms you can make two assumptions of your users:
- They want to use the product
- They probably have an understanding of some of the concepts
They do not understand:
- How your product works
- What they need to do to get the product to work for them
- Internal product terminology, use-cases, and related information
To explain anything to anyone you need to answer five questions:
- Who
- What
- When
- Where
- Why
Only after you’ve answered these questions, can you explain:
- How
- Who is the content for? (e.g., the audience)
- Who is the content not for?
- What is the purpose of the content?
- What is being documented? (e.g., a product, service, UI feature, functionality, etc)
- What assumptions are you making about the user’s skill-levels, what they know, etc?
- What dependencies exist for whatever is being discussed? (e.g., system in a certain state, Operating system, framework dependencies, application dependencies, etc)
- What is the actual order of events? (e.g., should the user have already performed/installed/completed something else before starting)
- What state should the system/application/source or target machine be in before performing any activities?
- When should the user be aware of different things? (e.g., is there an order of events)
- When is it appropriate to perform what is being discussed (e.g., certain conditions, certain dependencies in place; is it a workaround to an issue, etc)
- When is it not appropriate to perform what’s being discussed (e.g., Cloud functionality not the same as Community, etc)
- Where are things going to take place? (e.g., Cloud vs Community, specific UI, API vs CLI, etc)
- Where should this not be performed (e.g., Cloud vs Community again; Query editor only accepting certain types of SQL, etc)
- Where can the user pause in the process? (e.g., are there points they can stop and come back? If so, are there logical breaks you can add in?)
- Where does the user perform different actions (e.g., their database, JSON files, CLI, API, Cloud or Community UI, etc) and is there sufficient information to guide them to these?
- Why is the user here?
- Why this method and not another?
- Why do this at all?
IMPORTANT: You can ONLY answer this question once the previous ones are answered.
These questions are basically covered in process and procedure documentation.
- How does the user perform the task
- How should the system be set up before commencing the task?
- How does the system work once they’ve performed said task?
- How many changes of context are there in the sequence of steps (e.g., A set of UI pages, API vs UI, Source database vs CLI vs FeatureBase database)
- How are tasks performed in a logical order?