Documentation/Toolkit/Collection audit/Survey

This is Step 2 of the Documentation collection audit process. In Step 1, you determined the goals of your documentation: who your docs are for, and what they will help those people do. Now, you'll learn how your topic is covered in more places than you realized, and how it relates to other topics.

Understand the information landscape

Docs can be related to each other in multiple, overlapping ways. This is part of why navigation and maintenance are so difficult! In this step, you'll experience what your readers may feel when they try to find out about your topic. It's important to cast a wide net and gather as many docs as possible, even if they might be loosely related to your topic. This broad approach is important for multiple reasons:

1. You'll discover content you didn't know existed but which may be directly relevant to your topic, or might even contain content that will save you future work!
2. You'll build a mental model of the information space and how your topic fits into it.

Contextualizing your content within the larger doc landscape enables you to:

• • Create connections between docs: Help readers to navigate into, out of, and across documentation that is maintained by different groups of people.
  • Reduce information overload and improve UX: structure your content to reflect the user's journey, instead of reflecting opaque system architecture or organizational structures.
  • Make future maintenance easier: understand areas of likely content duplication, and areas you can safely ignore in future doc surveys.

In subsequent steps, you'll narrow the list of docs to a more manageable scope. But for now, get ready to dive into the ocean of docs.

Make a tracking document

Create a spreadsheet or another document to track the docs you identify during this step. Using a tracking doc for this process helps you standardize your analysis, understand the boundaries of your doc collection, and prioritize improvements across many docs.

Use the table on this page or copy this Google spreadsheet as a template for your tracking doc.

Avoid adding a generic "notes" field to your tracking doc. If you do that, much of the meaningful information you need will end up in a column that you can't use to sort and filter your list of docs.

Find the docs

To populate your tracking document with the list of docs you could assess, use some or all of the following techniques.

Explore landing page and subpages

Does your team or project already have a landing page? Use Special:PrefixIndex to identify subpages of your landing page. For example, to see the subpages of mw:Documentation, visit Special:PrefixIndex/Documentation/.

Add each of those subpages to your tracking document.

Browse by category

Check whether pages you discovered in the previous step belong to a specific category or set of categories. Browse the pages in those categories to identify additional pages that you should potentially consider part of your collection.

Collect linked pages

Do your docs use a navbox or other navigation template? If so, add all the pages that are linked in the navigation template to tracking document. Include all URLs, even those that aren't wiki pages.

Pull additional links from key docs:

• If you already know some docs in your topic area that are the most important: add to your tracking document any page that is linked to from those core docs.
  • As you do this step, start to note which links go to pages that don't contain crucial information related to your topic, nor help the reader complete the essential tasks that you identified when you were defining your documentation's goals.
  • In your tracking spreadsheet, create a column or mechanism to mark these pages as "potentially not in scope" (in the template, this is the "Relevance" column).
• If you don't already know which docs in your topic area are the most important, move on to the next step.

Search

• Search across multiple wikis (like MediaWiki, Meta, and Wikitech) for keywords related to your project or topic. If you find relevant results, add the most prominent search results to your tracking spreadsheet if they're not already there (or just add them and deduplicate later).
  • If you didn't know which docs were most important for your topic area in the previous step, go back and use the docs you just found to complete the previous step.

• Search code repositories and static sites for relevant documentation. Use the Code Search tool and/or search in Github, Gerrit, Gitlab and https://doc.wikimedia.org/.

If you identify individual pages that should belong to your collection, but are not currently connected to it, consider how to fix that. The best options are adding pages to your navigation template, adding them to a Category, or linking to them in an appropriate and prominent location. If there's not an obvious solution, file Phabricator tasks or use your preferred mechanism to record this work for later.

Next step

You should now be feeling overwhelmed. :-) In the next step, you'll narrow your list by analyzing the relevance and importance the docs you've identified. Go to Step 3.