<div dir="ltr"><div>Oh absolutely. Documentation issues lead to more support problems in the long term etc etc... I like your idea of "Lexical Debt"!</div><div><br></div><div>Jo<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jun 19, 2019 at 8:46 AM Jared Morgan <<a href="mailto:jaredleonmorgan@gmail.com">jaredleonmorgan@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><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" target="_blank">jo.k.cook@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);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" rel="noreferrer" target="_blank">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" rel="noreferrer" target="_blank">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" rel="noreferrer" target="_blank">a peer or a piece of content</a>? A low point was discovering two repos <a href="https://github.com/multiformats/multicodec/issues/132" rel="noreferrer" target="_blank">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-m_274972403522192603m_3230448048712765662gmail_signature">------------------------<br><a href="http://about.me/jocook" rel="noreferrer" target="_blank">http://about.me/jocook</a></div></div></div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org" rel="noreferrer" target="_blank">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>
</blockquote></div><br clear="all"><br>-- <br><div dir="ltr" class="gmail_signature">------------------------<br><a href="http://about.me/jocook" target="_blank">http://about.me/jocook</a></div>