Once I joined Grammarly as a developer advocate, my first activity was to write down documentation for use the Grammarly Textual content Editor SDK with desktop apps constructed on Electron. Whereas I had expertise writing tutorials, articles, and READMEs, I had by no means written official product documentation.
I used to be in manner over my head. The clean web page downside was manner too actual. I used to be skilled in writing tutorials for particular examples, however I struggled with determining describe steps and ideas in a manner that was broadly relevant to a wide range of use circumstances. I went forwards and backwards in my thoughts about how a lot element to offer.
I pushed by the discomfort and, with the assistance of some high quality reviewers, revealed my first piece of official product documentation. Whereas I haven’t but come to like writing documentation, I’ve gotten higher at it over time.[/line_space]
If you happen to’re a developer or a software program engineer, chances are high good that you just’ve written documentation beforehand or might want to sooner or later. Maybe you’re writing official documentation to your customers or one thing extra casual, like inner documentation to your teammates or a README.
On this article, I’ll share ten finest practices for writing documentation that your readers will get pleasure from. With each finest observe, I’ll give a concrete instance associated to my expertise. By the top of the article, you’ll be prepared to write down documentation and perhaps, presumably, even excited in regards to the prospect of doing so.
Leap to:
2
Establish what must be documented
4
Write so your documentation is skimmable
5
Learn the model information (or choose one)
8
Decide your tolerance for outdated documentation
1
Learn (a few of) the docs 👀
If you happen to’re including on to an present set of documentation, begin by studying it. If you will get by all of it in an affordable period of time, learn all of it. If not, learn the necessary items just like the introduction, a getting began information, and one thing much like what you may be writing.
Search for patterns in how the documentation is structured and take into account how one can comply with that construction in your writing. Familiarize your self with key phrases and the extent of element offered, as you’ll need to match these points in your new documentation. In lots of circumstances, you’ll need to goal to your documentation set being so cohesive that it’ll look like it was written by one individual.
If you happen to discover one thing that’s complicated or that may very well be improved whilst you’re studying, take a word or open a ticket. Don’t get sidetracked into fixing every little thing immediately.
In my case, I began by studying the Textual content Editor SDK overview web page in addition to related pages for use the SDK with JavaScript, React, and Vue. I created a spreadsheet the place I famous any areas for enchancment, together with locations the place I turned confused or phrases that have been used inconsistently.
If you happen to’re writing a brand new set of documentation and don’t have the posh of studying present docs, do a light-weight learn of the documentation for related initiatives. Word what you want and what you don’t like. This gives you inspiration as you begin writing.
2
Establish what must be documented 🔍
The following factor you should do is establish what you should doc. Transcend simply the subject, and word the main points that you should doc. Contemplate factors like:
- What ideas do your readers want to know? Do you should clarify these ideas or hyperlink to different sources that specify them?
- What stipulations will your readers want to finish earlier than starting?
- What steps will your readers have to take?
- What’s going to the reader study or accomplish after studying your documentation?
- What variations of the software program does this documentation apply to? If you happen to’re documenting how two items of expertise work collectively, what variations of every are supported?
If you happen to’re not already an knowledgeable on the main points, dig in to study them. Maybe you do on-line analysis, maybe you attempt the steps your self, maybe you ask an knowledgeable questions, or maybe you do a mixture of all three. Maintain notes about issues that confuse you or the place you get caught. Make sure you element the steps you’re taking as a first-time person as a result of the expertise could also be completely different in subsequent tries.
If you happen to’re already an knowledgeable on the subject, take into account what you understand that your readers is not going to. Stroll by any steps in a recent setting; it’s straightforward to overlook that you just beforehand put in one thing months in the past whenever you tried it for the primary time your self.
My activity was to doc how builders can use the Grammarly Textual content Editor SDK in Electron apps. I met with members of our engineering crew for a video name. They walked me by the steps of including Grammarly options to an Electron app. In addition they confirmed me arrange related accounts for an Electron app, as a result of the steps have been completely different from the steps that have been already documented for net apps. I requested the engineers tons of questions and took plenty of notes. After the decision, I attempted including Grammarly options to an Electron app alone, detailing the steps I used to be taking. Admittedly, I bought caught a couple of occasions, and messaged the engineers on Slack to get clarification. By the top, I had an in depth listing of steps for the essential getting began circulation in addition to establishing related accounts.
3
Study your reader 🧑💻
If you happen to’re fortunate, somebody has already recognized your reader for you. If you happen to’re writing external-facing documentation, maybe your crew has already created detailed personas. If you happen to’re writing inner documentation to your crew, you understand your readers personally.
Attempt to reply the next questions on your reader:
- What’s your reader attempting to perform?
- What do they already know in regards to the subject?
- What ideas and phrases will likely be new to them?
- How does your reader need to discover the knowledge they want?
We didn’t have an in depth persona I might work from—we have been nonetheless amassing suggestions from our early beta launch of the SDK, and this function was on account of be launched the next week. I took my finest guess about our reader:
- They need to add communication help to their present Electron app.
- They’re already conversant in constructing Electron apps.
- They don’t know something in regards to the Textual content Editor SDK.
- They need clear written steps for getting began with the SDK, they need to skim the documentation to seek out what variations of Electron we assist, they usually desire a working code instance in GitHub.
4
Write so your documentation is skimmable 📝
Individuals hardly ever learn the complete set of documentation from begin to end. As an alternative, they’ll discover a web page that they suppose can have the knowledge they want after which skim it—beginning first with the headers after which drilling down into any sections that look related.
Listed below are some ideas for writing documentation that’s straightforward to skim:
- Use descriptive headers that enable your reader to shortly decide if a piece will present the knowledge they’re searching for.
- Write briefly paragraphs centered on a single thought.
- Use bulleted lists to share teams of knowledge.
- Use numbered lists to share sequential or ordered data.
5
Learn the model information (or choose one) 💅
Similar to a growth crew creates code formatting pointers, your crew can create a model information to your documentation. A mode information is a doc that gives guidelines and pointers for constant writing. If you write documentation, you should make a lot of selections the place the reply isn’t at all times clear and would possibly come right down to preferences. A mode information might cowl subjects like:
- Tone and ritual degree
- Grammar and formatting pointers
- The perfect studying degree
- Inclusive language pointers and phrases to keep away from
- How you can discuss necessary phrases and actions
- What use circumstances or themes to make use of for examples
A mode information supplies many advantages past simply consistency. It means that you can switch crew information to new teammates and supplies pointers for objects that might in any other case turn out to be irritating and time-consuming if revisited for each piece of latest or up to date documentation.
In case your crew already has a mode information, take the time to familiarize your self with it and reference it when you may have questions. In case your crew doesn’t but have a mode information, you can begin with a publicly obtainable one. Listed below are some examples:
If you happen to make a mode information choice that differs from or enhances the model information you’ve chosen, doc the choice in a spot like a crew wiki or a file in your code repo.
If you’re utilizing Grammarly Enterprise, you may codify your model information in Grammarly utilizing the model information function. The model information function means that you can create customized options to your crew. I’ve discovered I’m more likely to comply with a mode information after I get inline options than if I would like to recollect to use the rules myself.
Internally, we’ve an in depth model information at Grammarly that we’ve codified utilizing the Grammarly model information function. Which means each time I exploit Grammarly to investigate my writing, I get inline options custom-made to our firm’s most well-liked tone and model voice.
6
Construct code samples 🧑💻
A transparent code pattern might be value 1,000 phrases.
Builders generally skim documentation searching for code samples. They’re hoping that they will copy and paste code instantly into their utility and that the code simply works.
Listed below are some suggestions for constructing code samples:
- Write simply sufficient code to display the idea you’re describing within the documentation.
- Make sure the code pattern conforms to the very best practices of the programming language getting used.
- Optimize for readability over code effectivity.
- Word any stipulations which are wanted to ensure that the code to run (for instance, word any imports that ought to be on the high of the file or if the reader wants a particular model of one thing put in).
- Word if the pattern contains code that you don’t suggest for manufacturing use circumstances.
I personally love when product documentation features a manner for me to attempt the code in an interactive setting. The setup is quicker for me, and I’m a lot much less prone to run into surprising errors attributable to variations in my native setting.
Lots of the pages within the Grammarly for Builders documentation embrace embedded code snippets in addition to hyperlinks to CodeSandbox environments. Every CodeSandbox setting runs a code instance that we retailer within the Grammarly for Builders GitHub repository.
For instance, the documentation web page on the Grammarly Textual content Editor SDK for JavaScript comprises a number of quick code snippets, so readers can skim for the related code they want. The web page additionally embrace a hyperlink to an interactive instance on CodeSandbox. The interactive instance permits readers to see each the code for a whole, working instance in addition to a preview of the rendered instance.
7
Assessment your work ✅
It’s nearly sure that your first draft can have room for enchancment. You would possibly skip a key step, leaving your readers confused and pissed off. Otherwise you may need grammar errors or wordy sentences that distract or confuse your readers.
Much like code opinions, documentation opinions enhance high quality and unfold information throughout crew members. Create a documentation overview course of that is smart to your challenge. If you happen to’re writing inner documentation for one thing like establishing your growth setting, maybe you put up it in a crew wiki and ask the following one that tries it to present you suggestions or replace it themselves. If you happen to’re writing public documentation, you’ll seemingly desire a extra sturdy overview course of.
No matter whether or not you later ask somebody to overview your documentation, I strongly suggest you overview the documentation your self. Wait at the least a day after you end the primary draft earlier than doing all of your self-review so that you’re extra prone to catch errors. Listed below are some duties you’ll seemingly need to full as a part of your self-review:
- Learn by your documentation from high to backside to make sure it is smart.
- If you happen to’re writing a information with steps, attempt the steps your self in a recent setting.
- Use a communication assistant like Grammarly to make sure your writing is obvious, polished, and efficient.
- Step by any checklists your reviewers will use so that you just’re proactively catching something earlier than your reviewers do; this enables your reviewers to present you a higher-quality overview.
I like a overview guidelines to maintain opinions constant and guarantee nothing main will get skipped. Our Grammarly for Builders documentation has three ranges of opinions: a self-review, a technical overview, and a replica overview. I’ll share our overview checklists that you would be able to modify and use:
Technical overview guidelines
- The documentation precisely describes use and/or configure the performance.
- The documentation is full (covers all related points of the performance).
- The documentation contains right model necessities.
- The documentation comprises all related hyperlinks.
- The code samples comply with the given language’s finest practices.
- The documentation makes use of technical phrases appropriately.
- The code samples work.
- The steps work from high to backside in a clear growth setting.
Copy overview guidelines
- All photographs have acceptable alternate textual content.
- The documentation makes use of phrases appropriately and constantly.
- The hyperlinks within the documentation work as anticipated.
- The documentation group and circulation are logical.
- The documentation is grammatically right.
- The documentation follows the model information.
8
Decide your tolerance for outdated
documentation ⚖️
No matter you’re documenting is prone to change, and your documentation will most likely turn out to be outdated or inaccurate in some unspecified time in the future. Extremely motivated readers would possibly push by damaged documentation and determine it out themselves, however unmotivated readers would possibly merely hand over when one thing doesn’t work.
Contemplate your readers’ expectations and the time you need to commit to constructing and sustaining the documentation. In some circumstances, you may need a excessive tolerance for outdated documentation; you would possibly ask your readers to replace the documentation themselves or instantly chat with you in the event that they discover one thing now not works. In different circumstances, you may need a particularly low tolerance for outdated documentation; a damaged getting began information might have a massively unfavorable impression in your customers.
Decide your tolerance for outdated documentation and construct a course of accordingly. Listed below are some examples:
- Ask readers to contact you instantly in the event that they need assistance following the documentation
- Present contribution pointers so readers could make updates to the documentation themselves
- Add a survey widget to the documentation that enables readers to report points
- Present a dialogue discussion board the place readers can ask questions
- Embrace documentation updates in your merge guidelines
- Write automated exams to your documentation steps and code samples, so that you’ll know immediately if a code change ends in outdated documentation
We use a number of of those approaches on the Grammarly for Builders crew.
All the pages within the Grammarly for Builders documentation comprise a ranking widget. If a person supplies a low ranking, they’ve the choice of together with a touch upon how the web page might be improved.
We additionally enable readers to report points and ask questions within the Grammarly for Builders repository on GitHub.
Our launch course of requires the associated documentation to be included with function updates and releases. Our developer schooling crew attends the engineering crew’s day by day standups, so they’re saved within the loop on what’s being developed and altering. They work on the documentation all through the dash, ideally culminating in code and documentation that’s accomplished on the similar time.
9
Future-proof your visuals 😎
As I discussed earlier, no matter you’re documenting is prone to change. So how are you going to future-proof your visuals and decrease the upkeep price?
One of many best issues you are able to do is decrease the variety of screenshots and movies. I do know, I do know—visuals might be tremendous useful. Nonetheless, person interfaces continuously change, and the price of updating screenshots and animations is increased than the price of updating plain textual content. The price of updating movies is even increased.
When doable, use summary illustrations that aren’t tied on to the product UI. For instance, we show the animation beneath on our Person Suggestions web page. It illustrates the idea of person suggestions however doesn’t present the menu choices that result in the person suggestions survey. This animation will stay related even when our menus change.
Typically, a screenshot is one of the simplest ways to reinforce your textual content description. In these circumstances, decrease the quantity of the person interface that’s included within the screenshot.
For instance, when writing in regards to the Monitoring part of the Dashboard, I is perhaps tempted to incorporate a screenshot of the complete Grammarly Developer Hub UI.
As an alternative, I might crop the screenshot to solely present the Monitoring part. Which means if any of the navigation bars change, my screenshot remains to be correct.
10
Doc selections ⌨️
As you’re writing documentation, you’re seemingly going to seek out your self waffling about one thing: perhaps it’s a time period, perhaps it’s the verb you utilize to explain an motion the person is taking, or perhaps it’s how a lot of the display screen to incorporate in a screenshot. You would possibly waffle by your self, otherwise you would possibly pull in a teammate that will help you make the choice.
Every time making a decision, write it down. Put it in your model information.
Consistency in documentation is vital. When you decide a phrase for an idea, use that very same phrase each time. Synonyms usually are not your buddy. If you happen to use two completely different however related phrases, readers will marvel in case you are referring to the identical factor.
I like to recommend making a glossary of key phrases and definitions. Everytime you introduce a brand new idea, drop it in your glossary.
The glossary might stay publicly in your documentation or privately in your model information. I’ve discovered that choosing a time period is way simpler than creating a superbly wordsmithed definition. If you understand that you just’ll be tempted to debate and excellent the definition earlier than placing it someplace publicly, maintain an inner glossary with working, messy definitions. Perfecting the definition isn’t your high precedence proper now. The necessary factor is to select a time period and use it constantly.
Within the early days of making our Grammarly for Builders documentation, we needed to make plenty of selections. Usually this concerned discussions with our engineering crew in addition to the broader Writing and Content material Design crew at Grammarly. Listed below are some examples of selections we documented:
- When to make use of “Grammarly Textual content Editor SDK” vs “we” as the topic of the sentence
- How you can format inline code snippets
- What to call particular phrases and ideas (ultimately, we used the names we documented right here as the idea for an official glossary in our docs)
Abstract
On this article, I shared 10 finest practices for writing documentation:
2
Establish what must be documented
4
Write so your documentation is skimmable
5
Learn the model information (or choose one)
8
Decide your tolerance for outdated documentation
Like every ability, writing documentation is troublesome at first and turns into simpler the extra you observe. Don’t fret if you end up staring on the clean web page, questioning start. Discover a place to start out—it doesn’t should be the start—and jot down your whole ideas. The primary draft doesn’t should be anyplace near good.
I’d love to listen to from you! The place are you getting caught writing documentation? What ideas are you able to share? Begin a dialogue within the Grammarly for Builders repo on GitHub.