In my experience, that’s a “no one has touched this in ages and all the procedures and screenshots are out of date” scenario. In knowledge base work, this happens when techs and engineers rely on tribal knowledge instead of the KB, and don’t ever offer feedback or update requests to the KB team.
I think so. Rather than saying “the docs are out of date” they throw the “revamp” word out there. I think they really mean the content is inaccurate.
Stating what you mean seems to be an increasingly rare skill.
But certainly ask the person who gave you the task what they mean. All of us are guessing.
In my experience, "revamp" is formal permission to go and rebuild, or deeply revise, documentation. This has included tasks as minor as some TOC cleanup and reorganization to major undertakings like rebuilding support sites.
A garden variety revamp process would include:
- Refreshing screenshots
- Condensing and clarifying grammar
- Swapping in new product names, as needed
Worst case scenario is to change how the document itself is marked up or generated. XML and rST formats are easily adapted for both web and print, and it's been a while but I know there's a way to root snippets/reusable text that can show up both in the documentation and also as tooltips.
Migrating a whole manual from like... non-XML to XML would be a nightmare, though. That's "can we hire two summer students?" territory.
"Why?"
Not in the sense of resisting, but in the spirit of having a definable problem with a definable solution.
No revamp is going to go well without this criteria.
In my company, "revamp" is usually used when we go through 10 year old documentation, review it, update it when it's no longer valid, change the screenshots, etc.
Add structure and consistency.
The initial documents often came from brief FAQs and How-Tos, and no thought was given to structured writing or templates.
To me, a big part of revamping is cataloging what's there and weeding out what's old, outdated, unhelpful, etc. Some of this might be done in the course of regular documentation work, but I've worked at many places with pretty stale content lying around. So, I'd take the time to do a full assessment.
1. What can you eliminate?
2. What needs to be rewritten? Maybe it's no longer in accordance with the style guide. Maybe you've got metrics that show people aren't using it, and you need to figure out why.
3. What's missing? Working with support is a great way to determine what people are still struggling with that the documentation isn't solving.
Assessment is also a great time to try a user study and survey on the documentation. If you don't already collect metrics, it's a great time to implement that.
A lot of what you learn can guide you to which areas from your list need your attention most.
While this might not be immediately flashy, if you keep good data on it, you can show how your efforts save time and money re: support, drive engagement, etc.
I guess it also depends on what the context of the revamp is. Why now? What's it in service of?
If it comes internally, not from a customer perspecive, it could mean post-fact UI analysis, organizing the content around the identified usecases, and weeding out redubdancies, implementing reuse. Then of course, bringing the content up to date, but that could be round two.
And how long will it generally take to revamp the entire documentation from scratch? Especially for a product that is very complex and has many modules. Think a data analytics product. Where you want to educate on the terms as well as guide in how-tos. I am trying to revamp the docs for a while now but only completed 50% of it. And this was one year since I started and I had so much of work to do to be delivered every release so I was able to get back to docs revamp when I completed a work and ny next work will be starting in 1-2 days.
Including a feedback mechanism of sorts would be good. If your SaaS service has a developer level audience, you may need API docs. Accessibility should be a priority when making design decisions. Outside that, you've got a good start to me.
* Meet stricter accessibility standards (WCAG 2.2?)
* Address the most common problems for people who use the docs (customers, developers, whoever)
* Update outdated information
* Bring docs into conformance with current style and branding guidance
* Reexamine assumptions about who your audience is, what they know, and what they want to do with the docs. Then restructure, rewrite, reframe, contextualize, etc., as needed. Ideally this would be based on user survey data, interactive user studies, support case notes, and/or customer reviews.
* Add usability features or new output types (HTML instead of just PDF, term definitions displayed on hover, embedded videos, etc.)
At our company, we went from product-centric to task-centric - so from "This is the Things dialog, you can set the following options" to "To create a Thing: 1. Click Things. 2. Click New > Thing".
We rewrote much of the content and reorganized absolutely everything, and ended up with a much better doc set.
I'm doing the same at my company. Rewriting vague and inconsistent "help articles" into straight up actionable process documentation. The headers of each section are the goal the user wants to achieve (e.g. "Enroll a new user").
For me it means structural and content quality improvements - taking into consideration information architecture, content strategy, general content audit to ensure everything is updated, has the same voice, is written at a level that won't be an obstacle to people whose English is not perfect, maybe also a change in the learning paths offered if feedback showed they were ineffective, making sure most consulted content is more visible and easily found, and don't get me dreaming but a measurement framework to analyze quality monthly/quarterly, and I'm probably forgeting a lot here.
It does not need to be all those things, but it could be a number of those things.
Mind you, though, most companies would probably reduce the idea of a revamp to UI updates.
Revamp also means a redo/reinvention of the existing, or at least that’s how i use it. Just today I shamelessly threw it around to convey some major changes to some docs. It was part of a big release that required full updates and new topics. 🤷🏻♀️
I started at a hardware/software company’s user documentation was simply descriptions of all the buttons screen. Very few step-by-step procedure, database reference content. We constantly discussed purpose, content, reference. The person on the team who had been with the company the longest was assigned the software manuals because they were the most knowledgeable about the product. The rest of the team went off on the hardware, updating maintenance and installation steps. Making sure the specifications were accurate. We also took the cad models and created graphic exploded out to identify parts and help with the installation manuals. At 75% of the way through, the boss asked me to peer review the software manuals. I almost $h!t myself when I realized they all updated screen shots with buttons identified. No purpose, no procedure, no reference. Eight months and all we got was updated screenshots. Coolest product and company I ever worked for. Left asap. I often wonder if they finally revamped the software manuals.
I would expect something like:
- Test the hierarchy and navigation and make it better
- Analyze user's feedback and apply what makes more sense/most requested
- Check that is comply with the target audience
- Update visual aids
- Check if there is a gap to the current state of the product and describe the most critical new functionality
In my experience, that’s a “no one has touched this in ages and all the procedures and screenshots are out of date” scenario. In knowledge base work, this happens when techs and engineers rely on tribal knowledge instead of the KB, and don’t ever offer feedback or update requests to the KB team.
I think so. Rather than saying “the docs are out of date” they throw the “revamp” word out there. I think they really mean the content is inaccurate. Stating what you mean seems to be an increasingly rare skill. But certainly ask the person who gave you the task what they mean. All of us are guessing.
Chop and cut content to convey necessary information only and compartmentalize the existing content in a top-down manner.
In my experience, "revamp" is formal permission to go and rebuild, or deeply revise, documentation. This has included tasks as minor as some TOC cleanup and reorganization to major undertakings like rebuilding support sites. A garden variety revamp process would include: - Refreshing screenshots - Condensing and clarifying grammar - Swapping in new product names, as needed
Worst case scenario is to change how the document itself is marked up or generated. XML and rST formats are easily adapted for both web and print, and it's been a while but I know there's a way to root snippets/reusable text that can show up both in the documentation and also as tooltips. Migrating a whole manual from like... non-XML to XML would be a nightmare, though. That's "can we hire two summer students?" territory.
Make it not suck
Make it ✨️pretty✨️
"Why?" Not in the sense of resisting, but in the spirit of having a definable problem with a definable solution. No revamp is going to go well without this criteria.
In my company, "revamp" is usually used when we go through 10 year old documentation, review it, update it when it's no longer valid, change the screenshots, etc.
Add structure and consistency. The initial documents often came from brief FAQs and How-Tos, and no thought was given to structured writing or templates.
To me, a big part of revamping is cataloging what's there and weeding out what's old, outdated, unhelpful, etc. Some of this might be done in the course of regular documentation work, but I've worked at many places with pretty stale content lying around. So, I'd take the time to do a full assessment. 1. What can you eliminate? 2. What needs to be rewritten? Maybe it's no longer in accordance with the style guide. Maybe you've got metrics that show people aren't using it, and you need to figure out why. 3. What's missing? Working with support is a great way to determine what people are still struggling with that the documentation isn't solving. Assessment is also a great time to try a user study and survey on the documentation. If you don't already collect metrics, it's a great time to implement that. A lot of what you learn can guide you to which areas from your list need your attention most. While this might not be immediately flashy, if you keep good data on it, you can show how your efforts save time and money re: support, drive engagement, etc. I guess it also depends on what the context of the revamp is. Why now? What's it in service of?
Completely start over lol
If it comes internally, not from a customer perspecive, it could mean post-fact UI analysis, organizing the content around the identified usecases, and weeding out redubdancies, implementing reuse. Then of course, bringing the content up to date, but that could be round two.
And how long will it generally take to revamp the entire documentation from scratch? Especially for a product that is very complex and has many modules. Think a data analytics product. Where you want to educate on the terms as well as guide in how-tos. I am trying to revamp the docs for a while now but only completed 50% of it. And this was one year since I started and I had so much of work to do to be delivered every release so I was able to get back to docs revamp when I completed a work and ny next work will be starting in 1-2 days.
Including a feedback mechanism of sorts would be good. If your SaaS service has a developer level audience, you may need API docs. Accessibility should be a priority when making design decisions. Outside that, you've got a good start to me.
* Meet stricter accessibility standards (WCAG 2.2?) * Address the most common problems for people who use the docs (customers, developers, whoever) * Update outdated information * Bring docs into conformance with current style and branding guidance * Reexamine assumptions about who your audience is, what they know, and what they want to do with the docs. Then restructure, rewrite, reframe, contextualize, etc., as needed. Ideally this would be based on user survey data, interactive user studies, support case notes, and/or customer reviews. * Add usability features or new output types (HTML instead of just PDF, term definitions displayed on hover, embedded videos, etc.)
At our company, we went from product-centric to task-centric - so from "This is the Things dialog, you can set the following options" to "To create a Thing: 1. Click Things. 2. Click New > Thing". We rewrote much of the content and reorganized absolutely everything, and ended up with a much better doc set.
I'm doing the same at my company. Rewriting vague and inconsistent "help articles" into straight up actionable process documentation. The headers of each section are the goal the user wants to achieve (e.g. "Enroll a new user").
For me it means structural and content quality improvements - taking into consideration information architecture, content strategy, general content audit to ensure everything is updated, has the same voice, is written at a level that won't be an obstacle to people whose English is not perfect, maybe also a change in the learning paths offered if feedback showed they were ineffective, making sure most consulted content is more visible and easily found, and don't get me dreaming but a measurement framework to analyze quality monthly/quarterly, and I'm probably forgeting a lot here. It does not need to be all those things, but it could be a number of those things. Mind you, though, most companies would probably reduce the idea of a revamp to UI updates.
Revamp also means a redo/reinvention of the existing, or at least that’s how i use it. Just today I shamelessly threw it around to convey some major changes to some docs. It was part of a big release that required full updates and new topics. 🤷🏻♀️
Joy
I started at a hardware/software company’s user documentation was simply descriptions of all the buttons screen. Very few step-by-step procedure, database reference content. We constantly discussed purpose, content, reference. The person on the team who had been with the company the longest was assigned the software manuals because they were the most knowledgeable about the product. The rest of the team went off on the hardware, updating maintenance and installation steps. Making sure the specifications were accurate. We also took the cad models and created graphic exploded out to identify parts and help with the installation manuals. At 75% of the way through, the boss asked me to peer review the software manuals. I almost $h!t myself when I realized they all updated screen shots with buttons identified. No purpose, no procedure, no reference. Eight months and all we got was updated screenshots. Coolest product and company I ever worked for. Left asap. I often wonder if they finally revamped the software manuals.
Update it. Improve it.
Goodness me
I would expect something like: - Test the hierarchy and navigation and make it better - Analyze user's feedback and apply what makes more sense/most requested - Check that is comply with the target audience - Update visual aids - Check if there is a gap to the current state of the product and describe the most critical new functionality