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.

Identify your audience

 * Who is the audience or type of user this documentation should help?
 * For example, your audience might be "MediaWiki developers" or "new bot developers".
 * What pre-existing knowledge can you assume your audience has? Is there a range of technical expertise or understanding that you'll need to accommodate?

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.

Define the goals of your documentation collection

 * Why does someone need to know about the topics your docs cover? Try to fill in the following sentences:
 * "These docs will help ______ [audience] to understand what _____ [technology/project/process] is, and how to use it to _____ [do what?]."
 * "After visiting these docs, ______ [audience] should be able to ______ [do what?]."


 * What will happen if you don't create or improve these docs? What is the problem?
 * "Without these docs, ______ [audience] will continue to be confused about ______ [technology/project/process]."
 * "Without these improvements, it will be harder for ______[audience] to ______ [do what?]."

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, follow these steps:

1. Create a spreadsheet or another type of document where you can track the docs you encounter during this and the following steps. This list enables you to understand the boundaries of your doc collection, and help you organize and prioritize the doc improvements within that collection.

2. Understand how your collection relates to others: 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?

Explore:
 * Which docs do your docs link to? Do you understand why that connection exists? Is it necessary to achieve the goals of your documentation, or is it extra information?
 * Which docs link to your docs? Do you understand why that connection exists? What might readers who land on your docs from those other docs need to know? What would they be trying to achieve?


 * 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? Does it need to be updated, or can it just be deleted? Remember: technical documentation should not be encyclopedic. Only include information that your reader needs in order to accomplish their tasks.
 * Are there docs or sections of docs that aren't appropriate for your audience? Move these to a separate collection, or delete them.

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)