Introducing Project Swordfish [Organizing Content 2]
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.
About Tom Johnson
I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.