Focus group attendees spend some time brainstorming some of the features of good and bad documentation using a Jamboard. The key points made are summarised in the table below. This table may be helpful in helping you assess existing documentation or set out some basic principles for the creation of new documentation.
|
Features of good documentation |
Features of bad documentation |
|
Gathered in one known location that can be accessed by those who need to access it - easy to locate/discover - sits within logical documentation structure |
Is impossible to find or distributed across many locations |
|
It has a clear purpose and audience and contains the appropriate level of information targeted to their needs. |
Doesn’t take into account its audience - e.g. is overly technical, or assumes an unrealistic knowledge base. No consultation with audiences to see if it meets their needs. |
|
Up-to-date and well maintained. Clear which version it is. |
Out of date, lack of versioning information. |
|
Concise, simple and clear language. Easy to understand. Precise with no ambiguity. Terms are defined where necessary. |
Too long and too much jargon. Too technical and hard to understand. |
|
Clear who owns it and is responsible for maintaining it. Clear who to contact with questions or comments. |
Uncontrolled governance. No one knows whose responsibility it is to update it or who to go to if they have feedback. |
|
Well organized. Text is clearly formatted with numbering and bullet points. Includes step by step points with screen grabs and diagrams where appropriate. |
Poorly organized, with scattered information, dense paragraphs of text and no images. |
|
Clear how it relates to policies and other relevant documents. Part of a wider framework of documentation which forms the bigger picture |
Doesn’t take into account other organizational guidance and workflows. Unclear references, external links or dependencies. |
|
Tested for completeness (no missing steps). |
Inconsistent level of detail - step by step descriptions, but with gaps in the process. |
|
Uses standard template or house style for consistency. |
No consistency in style or conventions used. |
|
It is possible to see what has changed over time |
New versions are overwritten without any record of what has changed and when |
|
Clearly dated. Date of next review also clear |
Undated with no review schedule |