![]() ![]() If you’re already an expert on the topic, consider what you know that your readers will not. Be sure to detail the steps you’re taking as a first-time user because the experience may be different in subsequent tries. ![]() Keep notes about things that confuse you or where you get stuck. Perhaps you do online research, perhaps you try the steps yourself, perhaps you ask an expert questions, or perhaps you do a combination of all three. If you’re not already an expert on the details, dig in to learn them. What versions of the software does this documentation apply to? If you’re documenting how two pieces of technology work together, what versions of each are supported?.What will the reader learn or accomplish after reading your documentation?.What steps will your readers need to take?.What prerequisites will your readers need to complete before beginning?.What concepts do your readers need to understand? Do you need to explain those concepts or link to other resources that explain them?.Go beyond just the topic, and note the details that you need to document. The next thing you need to do is identify what you need to document. Identify what needs to be documented □ This will give you inspiration as you start writing. Note what you like and what you don’t like. ![]() If you’re writing a new set of documentation and don’t have the luxury of reading existing docs, do a light read of the documentation for similar projects. I created a spreadsheet where I noted any areas for improvement, including places where I became confused or terms that were used inconsistently. In my case, I started by reading the Text Editor SDK overview page as well as similar pages for how to use the SDK with JavaScript, React, and Vue. Don’t get sidetracked into fixing everything right away. If you find something that is confusing or that could be improved while you’re reading, take a note or open a ticket. In many cases, you’ll want to aim for your documentation set being so cohesive that it will seem like it was written by one person. Familiarize yourself with key terms and the level of detail provided, as you’ll want to match these aspects in your new documentation. Look for patterns in how the documentation is structured and consider how you can follow that structure in your writing. If not, read the important pieces like the introduction, a getting started guide, and something similar to what you will be writing. If you can get through all of it in a reasonable amount of time, read all of it. If you’re adding on to an existing set of documentation, start by reading it. Check out the recording!Ģ Identify what needs to be documented Ĥ Write so your documentation is skimmableĨ Determine your tolerance for outdated documentation I presented these best practices at Devoxx UK. By the end of the article, you’ll be ready to write documentation and maybe, possibly, even excited about the prospect of doing so. With every best practice, I’ll give a concrete example related to my experience. In this article, I’ll share ten best practices for writing documentation that your readers will enjoy. Perhaps you’re writing official documentation for your users or something more informal, like internal documentation for your teammates or a README. If you’re a developer or a software engineer, chances are good that you’ve written documentation previously or will need to in the future. While I haven’t yet come to love writing documentation, I have gotten better at it over time. I pushed through the discomfort and, with the help of some quality reviewers, published my first piece of official product documentation. Me staring at my blank screen, struggling to get started writing product documentation for the first time. I went back and forth in my mind about how much detail to provide. I was experienced in writing tutorials for specific examples, but I struggled with figuring out how to describe steps and concepts in a way that was broadly applicable to a variety of use cases. While I had experience writing tutorials, articles, and READMEs, I had never written official product documentation. ![]() When I joined Grammarly as a developer advocate, my first task was to write documentation for how to use the Grammarly Text Editor SDK with desktop apps built on Electron. ![]()
0 Comments
Leave a Reply. |