<story><title>Writing Documentation When You Aren&apos;t a Technical Writer</title><url>https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1</url></story><parent_chain></parent_chain><comment><author>kaycebasques</author><text>I&amp;#x27;m a technical writer. I write the docs for Chrome DevTools and Lighthouse.&lt;p&gt;The tips in this article are mostly fine. Nothing controversial there. It has some good advice, but ironically, the article itself doesn&amp;#x27;t follow its own advice.&lt;p&gt;&amp;gt; The first two paragraphs must state the most important information.&lt;p&gt;The most crucial skill for creating quality documentation is to &lt;i&gt;know your audience&lt;/i&gt; and then write for that particular audience. What knowledge are they bringing into the doc (and therefore you don&amp;#x27;t need to cover)? What knowledge are you assuming that they know? What if they don&amp;#x27;t have that knowledge? Hint: They&amp;#x27;ll probably find your doc confusing and frustrating. What is their likely emotional state going into a doc? E.g. if you&amp;#x27;re documenting an error code there&amp;#x27;s a higher chance that they&amp;#x27;re panicked, so don&amp;#x27;t waste their time! Given a particular audience, what exactly is &amp;quot;the most critical information&amp;quot;?&lt;p&gt;&amp;quot;Know thy audience&amp;quot; is one of those concepts where, the more you think about it, the less you realize you know. It&amp;#x27;s a lifelong journey. But the more you focus on this concept, the better &lt;i&gt;all&lt;/i&gt; of your communication will get.&lt;p&gt;I could go on for years about all sorts of interesting tips for improving your writing, but it&amp;#x27;s all a waste of time if you don&amp;#x27;t have an overarching guiding principle. And that principle is to know and write for your audience.</text></comment>
<story><title>Writing Documentation When You Aren&apos;t a Technical Writer</title><url>https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1</url></story><parent_chain></parent_chain><comment><author>rodionos</author><text>We adopted a set of formal guidelines [0] for our database docs, based on Google Developer Guide [1], and automated the checks as much as possible with linters [2].&lt;p&gt;The checks cover spelling, markdown formatting, broken links, and grammar&amp;#x2F;style. For instance, we specifically reject hostnames, domain names, IP addresses, person names, phone numbers unless it&amp;#x27;s on our Example List[3], which itself is largely based on RFCs.&lt;p&gt;[0]: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;axibase.com&amp;#x2F;use-cases&amp;#x2F;tutorials&amp;#x2F;workshop&amp;#x2F;technical-writing.html#grammar&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;axibase.com&amp;#x2F;use-cases&amp;#x2F;tutorials&amp;#x2F;workshop&amp;#x2F;technical-w...&lt;/a&gt;&lt;p&gt;[1]: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;developers.google.com&amp;#x2F;style&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;developers.google.com&amp;#x2F;style&amp;#x2F;&lt;/a&gt;&lt;p&gt;[2]: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;axibase&amp;#x2F;docs-util&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;axibase&amp;#x2F;docs-util&lt;/a&gt;&lt;p&gt;[3]: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;axibase.com&amp;#x2F;use-cases&amp;#x2F;tutorials&amp;#x2F;workshop&amp;#x2F;technical-writing.html#example-names&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;axibase.com&amp;#x2F;use-cases&amp;#x2F;tutorials&amp;#x2F;workshop&amp;#x2F;technical-w...&lt;/a&gt;</text></comment>