-
8/14/2019 Documentation Critique
1/4
MOVEiT DMZ Documentation Assessment
The following lists areas where the present MOVEiT DMZ
documentation might beimproved.
Global Issues
This table lists global issues--not linked with particular
topics, but are instead found
across the documentation.
Problem Description Priority
Need context
sensitive help
Users are more likely to find needed content if
they are not distracted by the extra task of hunting
to find the documentation.
High
Need centralized
glossary
It would be helpful to have a centralized list of
vocabulary items and definitions, accessible fromthe pages using
that vocabulary
Medium to
Low
Dont use passivevoice
Passive voice (The process will be run) makesit 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.
Medium toLow
Cluster concept
topics in a helpfulway
Concept topics should be grouped logically and
separately in the table of contents. Relatedconcept topics
should be grouped together.
Medium
Use examples toillustrate concepts
Difficult concepts should be illustrated withexamples, making
them easier for new users to
understand.
Medium toLow
Issues Specific to Certain Topics
Many of these issues occur across different topics, but only
affect a limited
Problem Description # of Topics
Affected
Priority
Many topics aretoo long
Topics should be short. Online text ismuch more readable in
short segments
(especially for someone short on timetrying to work
efficiently). Therefore
long topics should be broken up into
many separate shorter topics, and thesetopics should be broken
up into short
paragraphs.
98 Mediumto High
-
8/14/2019 Documentation Critique
2/4
Problem Description # of Topics
Affected
Priority
Need to describe
benefits/purpose offeatures
Users who access help tend to be
newbies. These users want to knowhow to perform a task, but also
what a
task is for and why they would want toperform it.
If a help topic is just for information
purposes, then the topic should begin
with info on why the information in thetopic is of interest to
readers.
35 Medium
to High
Content typesshould be separate
Documentation tends to fall into threecategories: Concept, Task,
and
Reference. (A fourth category is
Example, but these are less prevalent.)
47 Medium
Content formattingshould bestandardized
Documentation is easier to read if theuser always expects a
small, predictablenumber of formats for specific types of
content.
49 Medium
Use screenshots toillustrate concepts
and tasks
Especially if there are many features ona given page, a
screenshot with callouts
helps orient the reader. (While there are
some topics with screenshots, there areothers without.)
Screenshots should be
visible at the top of topics.
34 Medium
Dont provide
access-related infoto people alreadylogged in
You waste help system bandwidth if
you provide login information forpeople who are already logged
in. Omitat least for online version of help.
1 Medium
to Low
Need to call out
notes
If there is a paragraph that could qualify
as a Note, or Important, it should becalled out as such. It
makes the content
more varied and easier to read.
10 Medium
to Low
The print-friendly
link should be in
document itself
The print icon in the TOC is kind of
confusing. It is not an HLML page, but
appears with other HTML pages. Wouldit be better to have it
linked from one of
the other pages?
1 Medium
to Low
-
8/14/2019 Documentation Critique
3/4
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
whats 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 assignprivileges 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 Description
1. Name The name assigned to the group. Click the Name to view
andmodify the groups membership and properties.
2. Description A short description of the group (which you can
modify when youclick the groups Name).
3. Members The number of users contained in the group.
-
8/14/2019 Documentation Critique
4/4
4. Actions You can perform two actions on the group:
Click Clone to create a copy of the group, containing all
thegroups properties, which you can then modify for
yourpurposes.
Click Delete to delete the group. After you confirm thedeletion,
this action cannot be undone.
5. Navigation Use this tool to navigate to different sets of
groups. (Click here formore details.)
6. NumberAppearing
This is the number of groups appearing on each page. (Clicking
onthe Number Appearing link will allow you to modify this
setting.)
7. Add NewGroup
Clicking on the Add New Group link allows you to add a new
groupto the system and assign users to the group.
8. Select Groupsto View
Use this tool to filter your set of groups. (Click here for
moredetails.)
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
