Documentation Audit Checklist

Minimum Viable Documentation

Minimal Viable Documentation must be complete and accurate, with no broken links. Any provided code samples must be functional. To audit your first round of documentation, review each page with the following questions in mind:

• Is the content accurate?
• Is the content complete?
• Do all links work?
• Does all link text accurately describe the referral page?
• Do all code samples work?

Once you have completed the minimum viable documentation, you can incrementally improve developer experience.

Developer Experience

Use the questions below to evaluate the experience of developers using your documentation.

General

• Do the title and introduction clearly convey the goal of the guide?
• Can a user check their progress regularly?
• Do guides contain specific next steps?
• Do headers, titles and list items use consistent parts of speech, where possible?
• Are guides of a similar length, when appropriate?
• Do any guides need to be combined?
• Do any guides need to be separated?
• Do guides follow a generally consistent format?
• Is syntax consistent?
• Are internal terms defined?
• Are internal terms used consistently?

Readability

• Is the average readability score reasonably low?
• Do any difficult sentences need to be restructured or rewritten?
• Is active voice used?
• Are sentences overly wordy or flowery?
• Is there excessive marketing language?
• Is diminutive language avoided?

Organization

• Is the content of each guide presented in the order a user would need to find it?
• For example, introduction & prerequisites first, followed by steps, with troubleshooting & FAQ at the end.
• Are titles and headers accurate and concise?
• Are introductions and summaries accurate and concise?
• Do guides contain any unnecessary steps?
• Are optional steps clearly marked?
• Does each guide assume the user has completed only the getting started guide?
• If not, are the prerequisite guides properly referenced and linked?
• Are helpful resources easy to find early on in the process?
• For example, is the API reference easy to find?

Code Samples

• Do code samples retain proper formatting after being copied and pasted?
• Do code samples include enough context?
• For example, 1-2 lines above and below the snippet can be very helpful in knowing where to paste the code snippet
• Do code samples contain helpful comments, when necessary?
• Do code samples avoid excessive comments?
• For example, comments do not contain information that should included in the guide itself
• Are code samples properly highlighted?
• Are highlights consistent?

Scanability

• Are titles and headers of a similar length?
• Do titles avoid unnecessary repetition?
• For example, repeating your tool's name in each title is generally unnecessary
• Is information displayed in the most appropriate way? Including the following:
• Lists
• Tables
• Using colons effectively
• Are visual cues used appropriately?
• For example, "Step 1. Do X" is more scannable than "The first step is to do X"
• Do menus include information in the order most users would need to find it?
• Ex. Getting Started > Intermediate Information > Release Notes
• Is there an obvious path to follow, or do users have to click around to find resources?

Style

• Is the voice appropriate?
• Is the voice consistent throughout the documentation?
• Are headers styled appropriately?
• For example, H3s are smaller than H2s
• Are headers styles consistent across pages?

Other

Specific Sections

In addition to the above, evaluate the following specific pages with the following questions:

• Landing Page: Do items on the landing page include clear call to actions?
• Getting Started:
• Does the getting started guide start with the assumption that the user has minimal knowledge of the product?
• Is the getting started guide easy to find from the landing page?
• Is the getting started guide properly scoped?

Maintainability

Documentation that is not maintainable is at a higher risk of becoming inaccurate over time. The following questions are helpful as you evaluate the maintainability of your documentation.

• Are screenshots properly simplified?
• Is duplicate information avoided?
• Within the same guide
• Multiple pages with the same information
• Does the documentation avoid providing instructions to using a third-party app?