[SeasonOfDocs] How not to do documentation

[Jo Cook]

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