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.  That understanding is crucial because contextualizing your content within the larger doc landscape enables you to:
 * Create connections between docs that better enable readers to navigate into, out of, and across documentation that is maintained by different groups of people.
 * Reduce information overload and improve UX by structuring content to reflect the user's journey, instead of reflecting opaque system architecture or organizational structures.
 * Making future maintenance easier by understanding likely areas of 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.

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.

Landing page
Does your team or project already have a landing page? Use Special:PrefixIndex to identify subpages of your landing page and add each of those pages to your tracking document.

Category
Check whether pages discovered in the previous step (landing page and its subpages) belong to a specific category or set of categories. Then, investigate if these categories contain any additional pages, not identified in the previous step, that should be considered part of your collection.

Linked pages and information hubs
Do your docs use a navbox or other navigation template? If so, add to your tracking document all the docs that are linked in the navigation template.

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, note which links are superfluous or unnecessary. These 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 the previous step. 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 docs at the top of the 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 of adding to your tracking document the pages linked to from your key docs.


 * 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.

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.