Documentation Critique
This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA
Overview
Download & View Documentation Critique as PDF for free.
More details
- Words: 902
- Pages: 4
MOVEiT DMZ Documentation Assessment The following lists areas where the present MOVEiT DMZ documentation might be improved.
Global Issues This table lists global issues--not linked with particular topics, but are instead found across the documentation. Problem Need context sensitive help Need centralized glossary Don’t use passive voice
Cluster concept topics in a helpful way Use examples to illustrate concepts
Description Users are more likely to find needed content if they are not distracted by the extra task of hunting to find the documentation. It would be helpful to have a centralized list of vocabulary items and definitions, accessible from the pages using that vocabulary Passive voice (“The process will be run”) makes it more difficult for users to picture “who is doing what to whom.” Short sentences with clear subjects and objects are much easier to read in online help. Concept topics should be grouped logically and separately in the table of contents. Related concept topics should be grouped together. Difficult concepts should be illustrated with examples, making them easier for new users to understand.
Priority High Medium to Low Medium to Low
Medium Medium to Low
Issues Specific to Certain Topics Many of these issues occur across different topics, but only affect a limited Problem
Description
Many topics are too long
Topics should be short. Online text is much more readable in short segments (especially for someone short on time trying to work efficiently). Therefore long topics should be broken up into many separate shorter topics, and these topics should be broken up into short paragraphs.
# of Topics Affected 98
Priority Medium to High
Problem
Description
Need to describe benefits/purpose of features
Users who access help tend to be “newbies.” These users want to know how to perform a task, but also what a task is for and why they would want to perform it.
Content types should be separate Content formatting should be standardized Use screenshots to illustrate concepts and tasks
Don’t provide access-related info to people already logged in Need to call out notes The print-friendly link should be in document itself
If a help topic is just for information purposes, then the topic should begin with info on why the information in the topic is of interest to readers. Documentation tends to fall into three categories: Concept, Task, and Reference. (A fourth category is Example, but these are less prevalent.) Documentation is easier to read if the user always expects a small, predictable number of formats for specific types of content. Especially if there are many features on a given page, a screenshot with callouts helps orient the reader. (While there are some topics with screenshots, there are others without.) Screenshots should be visible at the top of topics. You waste help system “bandwidth” if you provide login information for people who are already logged in. Omit at least for online version of help. If there is a paragraph that could qualify as a Note, or Important, it should be called out as such. It makes the content more varied and easier to read. The print icon in the TOC is kind of confusing. It is not an HLML page, but appears with other HTML pages. Would it be better to have it linked from one of the other pages?
# of Topics Affected 35
Priority
47
Medium
49
Medium
34
Medium
1
Medium to Low
10
Medium to Low
1
Medium to Low
Medium to High
Sample Recommended Help Page The following is a suggested format for the online help, including screenshot, callouts, and references to task and concept topics. This would be a Reference page, describing what’s on the screen. It links to external Task and Concept pages. This is only a mockup, and may or may not be accurate.
Groups This page allows you to view and modify MOVEiT groups. Groups allow you to assign privileges and action rules across a number of users that you assign to that group. Note: This page is only available if you have Administrator privileges.
This page contains the following items: Item 1. Name 2. Description 3. Members
Description The name assigned to the group. Click the Name to view and modify the group’s membership and properties. A short description of the group (which you can modify when you click the group’s Name). The number of users contained in the group.
4. Actions
5. Navigation 6. Number Appearing 7. Add New Group 8. Select Groups to View
You can perform two actions on the group: Click Clone to create a copy of the group, containing all the groups properties, which you can then modify for your purposes. Click Delete to delete the group. After you confirm the deletion, this action cannot be undone. Use this tool to navigate to different sets of groups. (Click here for more details.) This is the number of groups appearing on each page. (Clicking on the Number Appearing link will allow you to modify this setting.) Clicking on the Add New Group link allows you to add a new group to the system and assign users to the group. Use this tool to filter your set of groups. (Click here for more details.)
Note: When you create a group, you must assign it at least one user.
See Also:
About Groups
About Users
About User Privileges
About Action Rules
Global Issues This table lists global issues--not linked with particular topics, but are instead found across the documentation. Problem Need context sensitive help Need centralized glossary Don’t use passive voice
Cluster concept topics in a helpful way Use examples to illustrate concepts
Description Users are more likely to find needed content if they are not distracted by the extra task of hunting to find the documentation. It would be helpful to have a centralized list of vocabulary items and definitions, accessible from the pages using that vocabulary Passive voice (“The process will be run”) makes it more difficult for users to picture “who is doing what to whom.” Short sentences with clear subjects and objects are much easier to read in online help. Concept topics should be grouped logically and separately in the table of contents. Related concept topics should be grouped together. Difficult concepts should be illustrated with examples, making them easier for new users to understand.
Priority High Medium to Low Medium to Low
Medium Medium to Low
Issues Specific to Certain Topics Many of these issues occur across different topics, but only affect a limited Problem
Description
Many topics are too long
Topics should be short. Online text is much more readable in short segments (especially for someone short on time trying to work efficiently). Therefore long topics should be broken up into many separate shorter topics, and these topics should be broken up into short paragraphs.
# of Topics Affected 98
Priority Medium to High
Problem
Description
Need to describe benefits/purpose of features
Users who access help tend to be “newbies.” These users want to know how to perform a task, but also what a task is for and why they would want to perform it.
Content types should be separate Content formatting should be standardized Use screenshots to illustrate concepts and tasks
Don’t provide access-related info to people already logged in Need to call out notes The print-friendly link should be in document itself
If a help topic is just for information purposes, then the topic should begin with info on why the information in the topic is of interest to readers. Documentation tends to fall into three categories: Concept, Task, and Reference. (A fourth category is Example, but these are less prevalent.) Documentation is easier to read if the user always expects a small, predictable number of formats for specific types of content. Especially if there are many features on a given page, a screenshot with callouts helps orient the reader. (While there are some topics with screenshots, there are others without.) Screenshots should be visible at the top of topics. You waste help system “bandwidth” if you provide login information for people who are already logged in. Omit at least for online version of help. If there is a paragraph that could qualify as a Note, or Important, it should be called out as such. It makes the content more varied and easier to read. The print icon in the TOC is kind of confusing. It is not an HLML page, but appears with other HTML pages. Would it be better to have it linked from one of the other pages?
# of Topics Affected 35
Priority
47
Medium
49
Medium
34
Medium
1
Medium to Low
10
Medium to Low
1
Medium to Low
Medium to High
Sample Recommended Help Page The following is a suggested format for the online help, including screenshot, callouts, and references to task and concept topics. This would be a Reference page, describing what’s on the screen. It links to external Task and Concept pages. This is only a mockup, and may or may not be accurate.
Groups This page allows you to view and modify MOVEiT groups. Groups allow you to assign privileges and action rules across a number of users that you assign to that group. Note: This page is only available if you have Administrator privileges.
This page contains the following items: Item 1. Name 2. Description 3. Members
Description The name assigned to the group. Click the Name to view and modify the group’s membership and properties. A short description of the group (which you can modify when you click the group’s Name). The number of users contained in the group.
4. Actions
5. Navigation 6. Number Appearing 7. Add New Group 8. Select Groups to View
You can perform two actions on the group: Click Clone to create a copy of the group, containing all the groups properties, which you can then modify for your purposes. Click Delete to delete the group. After you confirm the deletion, this action cannot be undone. Use this tool to navigate to different sets of groups. (Click here for more details.) This is the number of groups appearing on each page. (Clicking on the Number Appearing link will allow you to modify this setting.) Clicking on the Add New Group link allows you to add a new group to the system and assign users to the group. Use this tool to filter your set of groups. (Click here for more details.)
Note: When you create a group, you must assign it at least one user.
See Also:
About Groups
About Users
About User Privileges
About Action Rules
Related Documents
Documentation Critique
May 2020 14
Critique
May 2020 29
Documentation
May 2020 24
Documentation
November 2019 42
Documentation
November 2019 34