Documentation/Planning for better technical documentation

This page contains information to help you audit a collection of technical documentation and determine a strategy to improve it.

Define your goal

 * Who is the audience or user this documentation should help?
 * For example, your audience might be "MediaWiki developers" or "new bot developers".
 * What is the user trying to accomplish? What tasks must they complete -- and what concepts must they understand -- to achieve their goals?
 * (TODO: examples)

Identify the docs to improve
Docs can be related to each other in multiple, overlapping ways. For example, sets of documents usually exist for a given topic, audience, process, or product. It's easier to identify documentation tasks if you start by collecting the content relevant for your goal. To do that, consider the following questions:


 * TODO Step one: define your collection concept
 * TODO Steps two+: how to locate content related to your collection concept
 * One technique for finding this content: follow all the links from a landing page or main content page for your topic (TODO: link to a script to pull all the links from a given wiki page). As you do this, note which links are superfluous and don't really help the reader understand crucial information related to your topic, or complete essential tasks that you identified when you were defining your goal in the previous step.

Assess information overload
For each of the docs in your collection, skim the content and keep track of your impressions of the following data points (a spreadsheet works great for this):


 * Is there content that is already covered elsewhere, or should not be covered in these docs?
 * For example, if the user's goal is "create a bot", they may need to have a basic understanding of a large range of concepts, like MediaWiki APIs, Wikitext and the structure of wiki pages, bot accounts, and coding conventions. However, 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.
 * What content is outdated and needs to be deleted?

Assess information gaps

 * Are there any features that are undocumented?
 * Go to a page 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, or (TODO: examples)
 * Be a subpage of a more general document where the reader can back up to go learn what they need if they landed on this page without context. (TODO: examples)