Docs rescue
Got messy, ugly docs? Users can't find what they need? Sprawling pages of outdated, unclear info? Contributors getting frustrated? Start with high-impact quick fixes, followed by gradual improvements on the rest.
- Identify the key pages to fix immediately.
- Make quick improvements to searchability, to mitigate problems with organisation.
- Figure out what you can delete, and what you need to update (eventually).
- Ensure the docs tooling provides:
- A modern look and feel.
- A supportive user and contributor experience.
- Make sure the problems won't recur.
Some docs may be harmed in this process
A key part of rescuing docs is deleting docs. Brace yourself!
Deliverables
The following table outlines my main docs rescue offerings, and what they bring to your company.
You can choose whether I act exclusively as a consultant, advising and planning, or whether I also carry out the implementation steps.
There are two streams of work running in parallel:
- Identify the most impactful docs, and prioritise fixing them. This means your users benefit from the work - fast.
- Identify what your contributors need to succeed, and set that up. This helps avoid repeated problems, and makes it easier for your contributors to tackle the rest of the overhaul work.
| Deliverable | Benefits | |
|---|---|---|
| Diagnosis | Analytics: identify needs and set up reports | Avoid gathering data for the sake of it. Know what you're gathering, design meaningful reports, and understand what to do in response to it. |
| Review of your research | A review of your existing user and competitor research, from a docs point of view. Generates docs-specific insights from your existing data. | |
| Review current processes and tooling | Understand your docs contributors as users of your process and tooling. Are they set up for success? | |
| Strategy | One-page strategy | Define your objectives, and who is writing and reviewing. |
| Audience definition | Get clarity about who your audience is and what problems they're trying to solve when they visit your docs. | |
| Tactics | Content plan | Based on the audience and objectives, define a documentation content plan and information architecture. This includes determining which docs are high priority, and which could be dropped. |
| Content types and templates using Diátaxis | Each page in your docs has a defined content type and structure, designed to meet the user's needs. The templates improve contributor experience and efficiency. The Diátaxis model is simple but effective. The templates are customised to your product and audience. | |
| Style guide | Make sure you have a usable style guide: your contributors and users both benefit from clarity. | |
| Process and tooling | Decide on any changes, based on the contributor needs identified during diagnosis. | |
| Searchability | Search is extra-important in a messy docs site. Consider adding AI-powered search, as well as making sure traditional search is up to scratch. | |
| Implementation | Actually write the docs! I offer coaching to make sure your contributors can create better docs going forward. I also offer editing services to overhaul existing content for clarity and consistency. | |
Timeline, pricing, process
The length of the project depends on which elements you choose, your availability, and how much coaching and implementation work is required. A typical range is anything from two to six weeks.
I provide a custom pricing quote for every client. This allows for the wide variation between different docs projects.
The process:
- Contact me
- We have an initial call to discuss your needs.
- I provide a statement of work, detailing deliverables, time estimate and pricing quote. I can provide a contract, or we can use your company's own legal docs.
- Once you've signed, we start the project! You'll need to grant me access to some of your company's systems and data. Usually this includes your user research, analytics, and docs repository.
- You'll review every deliverable as we go to make sure I'm on track.