<div dir="ltr"><div>Hi All,</div><div><br></div><div>This: <a href="https://macwright.org/2019/06/08/ipfs-again.html">https://macwright.org/2019/06/08/ipfs-again.html</a> is an interesting article with some important takeaways about documentation. It's about IPFS, which is a fairly techy and young piece of web technology, but as an overview- it's had a lot of money thrown at it but there are some major roadblocks in terms of documentation that mean it's really hard for even a very techy person to get to grips with. I think there are some lessons here that could be incorporated into our own guidelines.</div><div><br></div><div>if you don't fancy reading through the whole article, then the problems and recommendations at the end are the place to look. Quoting:</div><div><br></div><div>-------------------------------------------------------</div><div></div><div><p>An overextended, under-documented, and unfinished constellation of 
projects. No single part of the ecosystem is truly finished and 
well-documented, and new parts are spawned every day. Projects that are 
almost universally avoided – like IPNS – are still included in the main 
documentation and recommended as if they’re usable.</p><p>The same goes 
for language: IPFS has a sprawling set of jargon that’s inconsistently 
used. Is it merkledag or merkle-dag? There are enough terms that there’s
 a <a href="https://github.com/ipfs/glossary">glossary</a>, but the glossary itself refers to both merkle-dag and merkledag. Is a node <a href="https://discuss.ipfs.io/t/ipfs-jargon-the-double-meaning-of-node/5534">a peer or a piece of content</a>? A low point was discovering two repos <a href="https://github.com/multiformats/multicodec/issues/132">whose readmes referred to each other as the same thing</a>.</p><p>*snip*</p><p>First, make recommendations. I went down the IPNS rabbit hole because the documentation sent me, and only by a chance encountered did I learn that it’s almost universally avoided. There’s no shame in saying that a project’s not ready. Recommending unusable projects burns goodwill. Recommend paths that work.</p><p>Secondly, fix your words. Words are work, and that work is not happening. Finish a glossary, standardize usage and meaning, and cull unnecessary jargon. Treat new bits of jargon like technical debt, because that’s what they are.</p><p>------------------------------------------------------------<br></p></div><div>The take-aways for me are:</div><div><br></div><div>1) Ensure you keep jargon to a minimum and be consistent in your naming. For new users, inconsistencies are a nightmare as they (we) all want concise instructions that "just work".</div><div><br></div><div>2) Ensure new features are documented, and that old methodologies, features, and approaches are deprecated and marked as such. Similarly, if a feature is in development, or perhaps incomplete, by all means document it but ensure it's clearly flagged up.<br></div><div><br></div><div>3) Bad documentation puts people off!</div><div><br></div><div>Thanks for reading,</div><div><br></div><div>Jo<br></div><div><br></div><div><br>-- <br><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature">------------------------<br><a href="http://about.me/jocook" target="_blank">http://about.me/jocook</a></div></div></div>