<div dir="auto">"Treat jargon like technical debt"<div dir="auto"><br></div><div dir="auto">I love that notion.</div><div dir="auto"><br></div><div dir="auto">I almost reckon we could adapt that term of "Technical Debt" like hacks made to docs and TODOs left undone as "Lexical Debt".</div><div dir="auto"><br></div><div dir="auto">Could be a good conference topic.</div><div dir="auto"><br></div><div dir="auto"><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon., 10 Jun. 2019, 21:32 Jo Cook, <<a href="mailto:jo.k.cook@gmail.com">jo.k.cook@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>Hi All,</div><div><br></div><div>This: <a href="https://macwright.org/2019/06/08/ipfs-again.html" target="_blank" rel="noreferrer">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" target="_blank" rel="noreferrer">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" target="_blank" rel="noreferrer">a peer or a piece of content</a>? A low point was discovering two repos <a href="https://github.com/multiformats/multicodec/issues/132" target="_blank" rel="noreferrer">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="m_3230448048712765662gmail_signature" data-smartmail="gmail_signature">------------------------<br><a href="http://about.me/jocook" target="_blank" rel="noreferrer">http://about.me/jocook</a></div></div></div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank" rel="noreferrer">SeasonOfDocs@lists.osgeo.org</a><br>
<a href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs" rel="noreferrer noreferrer" target="_blank">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote></div>