Documentation/Toolkit/Collection audit/Assess

This is Step 4 in the Documentation collection audit process. In Step 3, you narrowed your focus to the most important documents. In this step, you'll assess those docs to determine what types of changes they need.

Assess information overload
For each of the pages in your collection (the docs you have listed in your tracking document): skim the content and keep track of your impressions for the following data points (the recommended spreadsheet from the previous step aligns with each of the following sections).


 * TODO: template
 * TODO: finish alignment of spreadsheet and the content here

Audience focus

 * Who is the audience or type of user this documentation should help?
 * For example, your audience might be "MediaWiki developers" or "new bot developers".
 * Are there docs or sections of docs that aren't appropriate for your audience? Move these to a separate collection, or delete them.

Don't combine documentation for different audiences. At the beginning of your docs and on your documentation landing page, declare who the intended audience of the docs is, and direct other audiences to the content that is made for them.

Content duplication
Is there content that is already covered elsewhere? If so, consider: is there any reason to cover it in this doc or set of docs?
 * Example: if a user's goal is "create a bot", they may need to understand a large range of concepts, like MediaWiki APIs, Wikitext and the structure of wiki pages, bot accounts, and coding conventions. A tutorial about how to create a bot should not cover all those concepts, because they are relevant for many topics beyond just bot development.  Instead, a bot tutorial should link to documentation that covers those topics, and clearly state at the beginning that understanding them is a prerequisite for completing the tutorial.

Content freshness

 * Is the content outdated? Does it need to be updated, or can it just be deleted?
 * Do the names of components or technologies used in the doc reflect the current reality, or have the names (or dependencies) evolved?

Missing content

 * Are there any features that are undocumented?
 * Are there requests for clarification or additional content on Talk pages or in Phabricator tasks?
 * Are you including the necessary information for the full range of technical expertise or understanding that your audience may have or not have? If you look at a doc and imagine that you know nothing about the topic, the page should:
 * Either: indicate prerequisite knowledge or steps at the beginning of the doc, and link to where the reader can go learn or complete them (example),
 * Or: be a subpage of a more general document where the reader can back up to go learn what they need to know, especially if they landed on this page without context.
 * Is it clear who is the maintainer of these docs, or where readers should ask questions about the content? Indicate whether you expect doc requests to come through Talk pages, Phabricator tasks, or other mechanisms.

Prerequisites and related content
This step helps you understand whether any of your content exists in isolation and is self-contained, or if it requires additional resources to provide readers with the full picture.

TODO: copypasta error Do you understand why that connection exists?


 * Is the content that links to your docs something that is essential for readers of your docs to understand? If so, do your docs cover that topic? Do they cover it by linking to the other doc, or do they duplicate that information?
 * What might readers who land on your docs from those other docs need to know? What would they be trying to achieve? Do your docs cover that?

Consider:
 * What upstream technology, processes, or systems should a reader be aware of before they can understand or use your docs?
 * What technical, social, or other dependencies impact your reader's ability to use the information in your docs? For example: must they have certain software installed, or must they have access to specific systems?

As you explore this, you may want to start filing Phabricator tasks to track issues like this to cleanup when you're done with your initial doc survey. While it's important to understand and improve connections between your docs and other docs, it's easy to get overwhelmed as you start to understand how your topic has content scattered across the wikiverse. Stay calm, remember the goals of your documentation, and focus on what your readers need to know to complete their key tasks.

Assess maintenance status
The steps in this section help you understand the problems others have faced when trying to work on these docs. Reviewing past and current maintenance efforts helps you identify pitfalls and avoid redoing work that others have already considered.

Phabricator tasks

 * Review the last 20 active Phabricator tasks that mention your key pages and/or your topic.
 * Reviewing by general topic can help you identify high priority content to improve or work on.
 * Reading the task history can help you identify how or why the content is difficult to change, manage, or fix.
 * Review the last 10 Phabricator tasks that were closed. How were they closed? Tasks closed without a fix might indicate some problems in the project.

Revisions
Starting with the most important docs in your collection, and proceeding through as many pages as possible, assess:
 * When was the last edit made? If it was long ago, is it because content can be considered stable, or abandoned?
 * How often do edits typically happen? Did the regular editors stop maintaining content for some reason?

This needs to be evaluated in context. When the project is stable, there is no longer any need to update its documentation. If a given project is actively developed, documentation might become outdated far quicker.

Maintainer outreach
If a page has notable recent activity like Talk page posts or significant recent edits, you should reach out to those people to understand their connection to the content. You may also want to contact the page creator. They may have ideas for how to improve the content, and they may be willing to help with your doc improvement work. If you think content should be moved or deprecated, it's a good practice to mention that to current or recent maintainers before you make such major changes.

Next steps
You may want to create Phabricator tasks to indicate the work needed for your list of docs, or you can use other mechanisms like posting on Discussion pages, using a tracking spreadsheet, or editing the pages directly to indicate the work needed.

Now: start fixing docs!
 * Delete or archive pages that you identified as obsolete.
 * Move content that isn't appropriate for your audience into another location. For example, content related to Wikimedia technical infrastructure should generally reside on Wikitech.
 * Reconcile duplicate content. Keep pages as short as possible and don't be afraid to delete extra information that doesn't help your reader understand crucial information or complete a task.
 * Use the Documentation Toolkit checklists to review and improve individual pages.