[SeasonOfDocs] How not to do documentation

[Jo Cook]

Oh absolutely. Documentation issues lead to more support problems in the
long term etc etc... I like your idea of "Lexical Debt"!

Jo

On Wed, Jun 19, 2019 at 8:46 AM Jared Morgan <jaredleonmorgan at gmail.com>
wrote:

> "Treat jargon like technical debt"
>
> I love that notion.
>
> I almost reckon we could adapt that term of "Technical Debt" like hacks
> made to docs and TODOs left undone as "Lexical Debt".
>
> Could be a good conference topic.
>
>
>
> On Mon., 10 Jun. 2019, 21:32 Jo Cook, <jo.k.cook at gmail.com> wrote:
>
>> Hi All,
>>
>> This: https://macwright.org/2019/06/08/ipfs-again.html 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.
>>
>> if you don't fancy reading through the whole article, then the problems
>> and recommendations at the end are the place to look. Quoting:
>>
>> -------------------------------------------------------
>>
>> 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.
>>
>> 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 glossary <https://github.com/ipfs/glossary>, but the
>> glossary itself refers to both merkle-dag and merkledag. Is a node a
>> peer or a piece of content
>> <https://discuss.ipfs.io/t/ipfs-jargon-the-double-meaning-of-node/5534>?
>> A low point was discovering two repos whose readmes referred to each
>> other as the same thing
>> <https://github.com/multiformats/multicodec/issues/132>.
>>
>> *snip*
>>
>> 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.
>>
>> 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.
>>
>> ------------------------------------------------------------
>> The take-aways for me are:
>>
>> 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".
>>
>> 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.
>>
>> 3) Bad documentation puts people off!
>>
>> Thanks for reading,
>>
>> Jo
>>
>>
>> --
>> ------------------------
>> http://about.me/jocook
>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>

-- 
------------------------
http://about.me/jocook
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190620/108ef4f9/attachment.html>