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 the goals of your documentation collection
Before you start assessing your docs, take a moment to consider why they should exist.


 * 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. To make it easier to identify and prioritize the documentation improvements that are in scope for your topic area, start by collecting the content relevant for your goal.

Recommended 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 (the recommended spreadsheet from the previous step works great for this).


 * TODO: template

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? Remember: technical documentation should not be encyclopedic. Only include information that your reader needs in order to accomplish their tasks.

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.

Assess information gaps

 * Are there any features that are undocumented?
 * Do the names of components or technologies used in the doc reflect the current reality, or have the names (or dependencies) evolved?
 * 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, or (TODO: examples)
 * 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.