Read & Write The Doc

Read & Write The Doc

A talk about the documentation and the issues we need to solve for readers and writers. I think there is more of a cultural problem around documentation than a technical one - and that's nothing practice and experience can't fix.

Also, I rant a bit about existing documentation, and that led to an opened issue on the Python's bug tracker. http://bugs.python.org/issue28499

1e88e032d61a9343dca0a7fc9cccc7b4?s=128

Florian Strzelecki

October 15, 2016
Tweet

Transcript

  1. 4.
  2. 6.

    Reader Issues • They found a non-official tutorial, – …

    which is outdated/use non-supported version – … and it is full of bad/deprecated practices • They ask questions on IRC first... – … and they were told to read the source, or the commit messages – … or they are told to RTFM • They rely on StackOverflow – … when they know how to use a search engine – … and use jQuery for everything • The doc says it's simple. They don't think so!
  3. 7.

    Writer Issues • They don't have time… (or their boss

    won't let them) • They wrote a README.txt and call it a day – … where they suggest to read the source – … that they never update – … that use an outdated version of a dependencies • They don't know how to start • They think nobody reads the doc anyway so why bother? • They rely on StackOverflow for that.
  4. 11.

    Readers are mostly users, but... • End-user will ask for

    a user manual • IT Administrator will ask for integration manual • Developpers will need quickstart, tutorials, API references, technical documentation, releaste notes, etc. • Maintainers will need docstring and testing tools • Product owner and software architect ask for specification, functional, technical, or both!
  5. 18.

    « It's an e-shop international application that provides car parts

    that fit customer's vehicle with facets. »
  6. 19.

    « It's an e-shop international application that provides car parts

    that fit customer's vehicle with facets. »
  7. 22.

    Entry points • Quickstart: how to start quickly • Tutorials:

    learn the basics • Chapters: dive into the features • References: technical details & API • FAQ: because StackOverflow is not available offline • Code: time to contribute • Install: not just on sysadmin day • Test suites: QA loves that one.
  8. 25.

    Step 1. • Write down all your ideas • Highlight

    what matter the most • Write 2 to 5 lines for each point
  9. 36.

    Personal content organization • Install • Configuration • Topics •

    Advanced topics • Dev-Guide / testing tools • Package reference (autodoc)
  10. 37.
  11. 38.

    Too Long, Didn't Read • What happened to the Django

    Documentation? • Why Python Documentation is so bad? • Third-level blocs are too big – and a bit messy. • A reference guide should contains one item per page only • What is wrong with the menu on the left?
  12. 39.
  13. 40.

    Bad Examples: the logging module • References are not well

    organized • The log attributes (what I look for 99 % of the time) is in the middle of the references – not easy to find. • A Basic Tutorial not so basic, not so advanced • An Advanced Tutorial that explains how logging works, but that's not what a tutorial is supposed to do • A Cook Book (sigh)
  14. 41.

    The problem is not the lack of content. There is

    just too much content. And it is not well organized.
  15. 43.

    Maybe better? • Intro (with basicConfig example) • Configuration (99

    % of readers's needs are here) • Logging Topic Guide (key concepts) • Reference guide (autodoc) • Cookbook (how to become a power user) • Extra content: tutorial
  16. 46.

    Quick Advices • Standardize your tone (too friendly to very

    formal) • Short sentence. • Subject is active. • Vocabulary should be accurate • Avoid digressions • Highlight few but important points
  17. 48.

    Quick Advices • Each part should be understandable with the

    least possible prerequisites • Don't repeat yourself: link related but distinct parts • Open to the outside worlds: link to norms, standards, and other project's documentations