| API documentation is autogenerated (e.g., by JavaDoc or Doxygen), and documents APIs completely (e.g., configuration files, property names, etc.). |
|
|
0.1 |
0.2 |
0.3 |
0.5 |
0.7 |
0.8 |
0.8 |
| Consists of clear, step-by-step instructions for use or adoption. |
|
|
0.1 |
0.1 |
0.2 |
0.3 |
0.4 |
0.5 |
0.5 |
| Documentation is held under version control alongside any code or other product components. |
|
|
0.1 |
0.2 |
0.3 |
0.5 |
0.6 |
0.8 |
0.8 |
| Documentation is on the project web site. |
|
0.1 |
0.2 |
0.2 |
0.3 |
0.5 |
0.6 |
0.8 |
0.8 |
| Documentation on the project web site makes it clear what version of the product the documentation applies to. |
|
0.1 |
0.2 |
0.2 |
0.3 |
0.5 |
0.6 |
0.8 |
0.8 |
| Does not use terms like “intuitive”, “user friendly”, “easy to use”, “simple” or “obviously”, unless as part of quotes from satisfied users |
|
|
|
0.1 |
0.1 |
0.1 |
0.3 |
0.3 |
0.3 |
| English language descriptions of commands and errors are provided but only to complement the above. |
|
|
|
|
|
0.2 |
0.5 |
0.8 |
0.8 |
| For common problems and error messages, the symptoms and step-by-step solutions are provided. |
|
|
|
0.1 |
0.1 |
0.3 |
0.7 |
1.0 |
1.0 |
| For software, a best-practice guideline is selected and code is validated against it. |
|
|
0.1 |
0.3 |
0.5 |
0.7 |
0.9 |
1.0 |
1.0 |
| Further information is suitable for the level of the reader, for each class of user. |
|
|
|
|
|
|
0.1 |
0.3 |
0.5 |
| Gives examples of what the user can see at each step, e.g., screen shots or command-line excerpts; installation outcomes; working examples and error examples. |
|
|
|
|
|
0.1 |
0.3 |
0.5 |
0.5 |
| Is task-oriented or objective-oriented. |
|
0.1 |
0.1 |
0.2 |
0.2 |
0.4 |
0.5 |
0.6 |
0.6 |
| Lists resources for further information. |
|
0.1 |
0.1 |
0.2 |
0.2 |
0.3 |
0.4 |
0.5 |
0.6 |
| Partitioned into sections for users, user-developers and developers (depending on the software). |
|
|
|
0.1 |
0.2 |
0.3 |
0.4 |
0.5 |
0.5 |
| Plain-text files (e.g. READMEs) use indentation and underlining (e.g. === and ---) to structure the text, and avoid TAB character indentation. |
|
|
|
|
0.1 |
0.1 |
0.1 |
0.2 |
0.2 |
| Provides a high-level overview of the product. |
0.1 |
0.2 |
0.3 |
0.4 |
0.5 |
0.6 |
0.8 |
1.0 |
1.0 |
| States assumed background and expertise of the reader, for each class of user. |
|
|
|
|
0.1 |
0.2 |
0.3 |
0.4 |
0.4 |
| States command names and syntax, says what menus to use, lists parameters and error messages exactly as they appear or should be typed; or provides similarly explicit instructions on how to apply product. |
|
|
|
|
|
0.2 |
0.6 |
1.0 |
1.0 |
| Uses teletype-style fonts for command line inputs and outputs, source code fragments, function names, class names etc.; uses appropriately styled fonts for key information and special terms or links. |
|
|
|
|
|
0.3 |
0.5 |
0.7 |
0.7 |