[SeasonOfDocs] How not to do documentation

[Jared Morgan]

"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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190619/dde19565/attachment-0001.html>