Search results

Introducing Project Swordfish [Organizing Content 2]

Series: Findability / organizing content

by Tom Johnson on May 17, 2010
categories: findability • technical-writing

  1. 1.0 New Series: Organizing Content [Organizing Content 1]
  2. 1.2 → Introducing Project Swordfish [Organizing Content 2]
  3. 1.3 Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]
  4. 1.4 Imposing Order Versus Observing Order [Organizing Content 4]
  5. 1.5 Topic-Based, Hierarchical Navigation [Organizing Content 5]
  6. 1.55 25 Facets for Navigation [Organizing Content 5]
  7. 1.6 Faceted Classification, Faceted Search [Organizing Content 6]
  8. 1.7 Implementing Faceted Classification/Search with a Help Authoring Tool [Organizing Content 7]
  9. 1.8 Second-Level Faceted Navigation [Organizing Content 8]
  10. 1.9 Browse Versus Search: Stumbling into the Unknown Unknown [Organizing Content 9]
  11. 2.0 Figuring Out Search Algorithms [Organizing Content 10]
  12. 2.1 Search Engine Optimizing Your Help Content for Google [Organizing Content 11]
  13. 2.2 From Help Authoring Tools to Web Tools, Especially Wikis [Organizing Content 12]
  14. 2.3 Using Mediawiki Templates to Organize Content [Organizing Content 13]
  15. 2.4 The Semantic Web and Content Findability: Interview with Patrick Warren [Organizing Content 14]
  16. 2.5 Faulty Assumptions About the Scope of Help Content? [Organizing Content 15]
  17. 2.6 Can Blogs Work as a Web Platform for Help? [Organizing Content 16]
  18. 2.7 Organizing Content as Story [Organizing Content #17]
  19. 2.8 Separating Basic from Advanced Topics: How Twitter Organizes Their Help [Organizing Content #18]
  20. 2.9 Emergence [Organizing Content #19]
  21. 3.0 Relying on the Wisdom of the Crowds with Help Authoring [Organizing Content #20]
  22. 3.1 Principles for Organizing Print Material [Organizing Content #21]
  23. 3.2 The Technical Writer as an Outsider: How Ambitious Are You? [Organizing Content #22]
  24. 3.3 The Interface Is Text [Organizing Content #23]
  25. 3.4 Best Practices for Writing Interface Text [Organizing Content #24]
  26. 3.5 Organizing for Learnability [Organizing Content #25]
  27. 3.6 Why Learning Software Is So Hard, and Organizing Content into Levels [Organizing Content #26]
  28. 3.7 Is Rhetoric Relevant? Considering the "Message in Context" [Organizing Content #27]
  29. 3.8 Organizing Content for Constructivist Learning [Organizing Content #28]
  30. 3.9 Eight Defining Questions that Shape Content Organization [Organizing Content #29]
  31. 4.0 Why Help Content Fails and #contentstrategy

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

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson