Introducing Project Swordfish [Organizing Content 2]
May 17th, 2010 | Posted in blog 5 Comments »
Welcome to the new project you’ll be documenting: Project Swordfish. Project Swordfish is an application used by the FBI to train agents in virtual simulations of undercover operations.
With Swordfish, users can be super agents and regular agents. The super agents can configure the permissions of the regular agents with 20 different permission settings. This means the relevant help topics for any agent can vary from about 10 topics to all 200 topics, depending on the permissions an agent has.
An agent with all 20 permissions will find that every topic in the help is relevant. An agent with no permissions will find that just a handful of topics in the help are relevant.
Some of the permission settings for the agents include the following:
- Allow agent to view master operations list
- Allow agent to create new operations
- Allow agent to close operations
- Allow agent to create operation maps
- Allow agent to add or remove members from his team
You get the idea. (By the way, this isn’t real.)
In Swordfish, agents are grouped into teams. The same agent can be on multiple teams, with different permissions on each team. For example, an agent can be a super agent on the Black Operations team, but a regular agent on the Public Operations team. Agents can even be double agents, so that they appear to be regular agents on a team but are actually super agents, and vice versa.
Project Swordfish has a moderately complicated interface that warrants approximately 200 help topics. Help topics include several types of topics: conceptual topics, task topics, videos, context-sensitive help topics, and FAQ topics. You need to create both an online help file as well as several printed guides. Your main task is to organize the help topics in a way that makes sense to users.
Content organization is the focus of this series, so that’s what the upcoming posts will explore — different ways to organize content from this hypothetical documentation scenario.
Sponsors
Tags: content organization, organization, permissions, roles, table of contents, Technical Writing
If you liked this post, keep updated with new content: Subscribe to I'd Rather Be Writing.
Both comments and pings are currently closed.
0 Subscribers
Mark Baker (7)
Greg DeVore (4)
Jonatan Lundin (4)
bg (3)
Jim Reardan (2)
Marcia Johnston (2)
mma (2)
Tammy P (2)
A Andrew (1)
Aldergrove drivin... (1)
I know I’m answering out of order
But one question I have is, how do agents know if they are super agents or regular agents?
And which statement is true?
- Super agents have anywhere from one to 20 permissions. Regular agents have no permissions.
- Super agents have all 20 permissions. Regular agents have anywhere from 0 to 19 permissions.
Users generally know what their role is.
The second statement is true — “- Super agents have all 20 permissions. Regular agents have anywhere from 0 to 19 permissions.”
But how do users know? Are they told? “Hey, Joe, you’re a regular agent with 15 permissions. Andy over there is a regular agent with 8 permissions, but only Rob is the super agent who can change which permissions you have.”
And another question: which statement is true?
- One permission setting (the SuperAgent Toggle) is never used by Regular Agents.
- Regular agents can have any combination of up to 19 permissions. (That is, there is no one “special” permission that applies only to SuperAgents.)
You’re right that some users really don’t know their role. Some aren’t aware of the fact that there are different roles. Most aren’t aware of the different permission settings that allow gradation of the roles.
To answer the other questions, “One permission setting (the SuperAgent Toggle) is never used by Regular Agents.” This is sort of true.
“Regular agents can have any combination of up to 19 permissions.” This is also true.
Basically, the idea of roles is an illusion. Roles are just a selection of different combinations of permissions. But to clarify the matter for most users, we are using these “roles” to refer to a pre-configured set of permissions. A user can have up to 20 permissions. Once a user has more than the regular set of permissions, that user is on his or her way to being a super user. But it’s a spectrum more than a yes or no.
I know I’m frustrating you a bit
, but here’s why:
In Day 4, you talked about the organization of the Periodic Table of Elements, and how Mendeleev needed to see the pattern to get the chart to work.
If users aren’t really aware of their role or that there are even roles to begin with means that any role-based headings should not be used…users will never realize when to use them. So that pattern cannot be used in navigation because users will never identify when or how they should use it.
Good navigational options require definites: the user knows he is a super agent or he knows he isn’t. (“On his way to being a super user” is too loose a definition to be useful for navigation. Technically, as soon as I have been assigned one permission, I’m on my way to being a super user.)
Using roles is fine when there is a visible delineation between roles that users immediately identify with. But when the distinction is fuzzy, roles shouldn’t be used (at least not for main navigational categories).