Zero to hero: User-facing documentation

<p>How we wrote a process to improve our user documentation’s quality assurance from scratch, and how you can do it too.</p><hr><p>A few months back, a B2B platform project I worked at was facing a tricky challenge. Our customer base had started to climb rapidly and our old, out of date docs weren’t doing us any favors anymore. Our classic workflow was educating customers in the use of the platform. That was done organically through a lengthy onboarding but as the product grew this process alone started to become ineffective in product education. Customers would get into the product with quite a few unanswered questions.</p><p>We didn’t have a dedicated customer support channel and much less a well-defined process on how to build useful and complete documentation. Setbacks were frequent. As the customer base grew, more and more questions started flooding our inboxes. From that point, we decided we needed to set up a process for documenting our changes and additions, new and old both, as there were quite a few cases of non existing basic documentation.</p><h3 id="the-process">The process</h3><p><a href="https://devchecklists.com/user-documentation-checklists/"><u>The checklist can be found here.</u></a></p><h4 id="step-1-"><strong>Step 1:</strong></h4><p>While on the last step of the development process, the developer follows the<a href="https://devchecklists.com/user-documentation-checklists/"> <u>checklist</u></a> twice: once while writing, once after they’re done.</p><h4 id="step-2-"><strong>Step 2:</strong></h4><p>The developer passes the docs along for someone else to review, preferably a developer or designer. These in turn review the documentation according to the standards of the same checklist.</p><h4 id="step-3-"><strong>Step 3:</strong></h4><p>If the documentation is standard-compliant, the documentation proceeds to the next step. If not, the developer corrects it.</p><h4 id="step-4-"><strong>Step 4:</strong></h4><p>The developer runs the documentation testing with people from other projects. They hand them the documentation and let them interact with the feature they wrote the documentation for. <strong>The developer doesn’t intervene during this process</strong>.</p><h4 id="step-5-"><strong>Step 5:</strong></h4><p>After that, the developer collects feedback about the process.</p><ul><li>From 0-10, indicate how much the documentation helped you in performing the features.</li><li>Which points did you have difficulty with?</li><li>Which points did you find good about the docs?</li><li>Any additional comments?</li></ul><h3 id="how-did-we-write-that-process">How did we write that process?</h3><p>We decided to update the documentation every time an epic was released. Our manager would always create documentation-specific tasks at the end of every feature cycle. These would count as sprint tasks with effort points attached. Well, we did manage to write more documentation. Cool, seems like we’ve sorted this out, huh?</p><p>Nope, our docs were unfortunately far from ideal. Writing user-facing docs is no easy task, it’s no coincidence there’s an entire position dedicated to it: technical writer. You can’t just take a group of engineers and ask them to write docs with no former instruction. You may luck out and have good results only, but that would be a perfect scenario, and not at all realistic one.</p><h3 id="a-second-try-please">A second try, please</h3><p>I decided to take it upon myself to write a small guide on how to write user-facing docs. I didn’t have any experience with that, therefore I couldn’t just start writing right away. I had to study. It took me a few weeks of researching thorough blog posts out there. In the end, I managed to write a simple checklist (although it looks more like a guideline) on how to build quality, comprehensive, and understandable user-facing documentation.</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://s3.amazonaws.com/vintasoftware-wagtail-ghost/blog/2020/09/userdocschecklist.png" class="kg-image" alt="Image showing a print screen of the checklist."><figcaption>(I'm so proud of my child) <a href="https://devchecklists.com/user-documentation-checklists/"><strong><u>You can check it out here, by the way.</u></strong></a></figcaption></figure><p>This has set a baseline for how our docs should be built and it definitely helped us understand what was absolutely important when writing documentation. Things such as being objective, explaining through images or GIFs, and minding terminology are mentioned in the guidelines, helping us every day when building our docs.</p><p>To avoid biases, we decided to have a review process. We could not guarantee that the documentation would be at its prime without it. If Pull Request reviews make sense to us, why wouldn’t documentation reviews be a thing too?</p><p>Every piece of documentation we wrote would have to be reviewed by another peer, who would then certify the documentation was in accord with our standards. That improved both the writer’s abilities as they got in touch with other ideas and the reviewers, by empowering them and turning them into expert revisers, making better writers in turn.</p><h3 id="one-last-issue-developer-bias">One last issue: developer bias</h3><p>The problem is that as product developers, sometimes we are in too deep. We weren’t exactly the best people to ensure these docs achieved its main goal: to educate customers in the product’s use. If there were any gaps, the chances our brains would automatically jump from A to C were high. Because of that, we needed an outsider’s perspective.</p><p>Each epic is now tested with a person from outside our team. At Vinta we have multiple projects so we call our colleagues once in a while and ask them to read our docs and test the new features out.</p><p>Not to interfere with the process we just hand the docs and wait for the tests’ results. This enabled detailed feedback of our blind spots and documentation adjustments followed.</p><h3 id="a-couple-of-takeaways-we-learned-the-hard-way-but-that-you-don-t-have-to-">A couple of takeaways we learned the hard way but that you don’t have to :)</h3><ul><li>Be organized with your time and everything will fit the timeline. Write your documentation ahead of time, schedule a review with a teammate at least two days before you apply the documentation testing process, so you’ll have some time to fix your docs if you get 3 pages worth of feedback.</li><li>If the tester does not get the general hang of the product, you should at least give them a tour before revealing a new feature. It’ll make feedback more precise.</li></ul><p>Thanks to Sidarta Varela, Cadu Macêdo, Diogo de Miranda and everyone at Vinta for reviewing this blog post!</p>

Zero to hero: User-facing documentation

Join the Tech Forward newsletter

Related articles

Pull Requests: Merging good practices into your project (part 1)

Vinta at PythonBrasil 2021

Building an ETL flow with asyncio, multiprocessing and asyncpg