Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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


Florian Strzelecki

October 15, 2016


  1. Read & Write The Doc PyconFR 2016 - @exirel

  2. Washing Machine https://commons.wikimedia.org/wiki/File:The_Ladies%27_home_journal_(1948)_(14768012505).jpg https://commons.wikimedia.org/wiki/File:LG%EC%A0%84%EC%9E%90,_%EB%AF%B8%EB%8B%88_%EB%93%9C%EB%9F%BC%EC%84%B8%ED%83%81%EA %B8%B0_%E2%80%98%EA%BC%AC%EB%A7%9D%EC%8A%A4%E2%80%99_%EB%8C%80%EB%A7%8C_%EC%B6%9C%EC%8B%9C_(2).jpg 1948 2014

  3. https://commons.wikimedia.org/wiki/File:Hk_protest_against_implementation_of_national_education_5.jpg What?

  4. None
  5. It's a cultural problem. And maybe a technical one too…

  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!
  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.
  8. … it's bad for everyone.

  9. What is documentation

  10. This is where we explain things for humans. But wait.

    What kind of documentation?
  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!
  12. (also skill levels)

  13. There is no one-size- fits-all documentation.

  14. Don't write one documentation. Write many.

  15. OK GOOD. HOW?

  16. Everything starts with a story. The product's story.

  17. The story gives cues to navigate, The keys to understand

    the product.
  18. « It's an e-shop international application that provides car parts

    that fit customer's vehicle with facets. »
  19. « It's an e-shop international application that provides car parts

    that fit customer's vehicle with facets. »
  20. Problem: story is linear. Solution: entry points are not.

  21. Different readers will take different paths. That's good !

  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.
  23. Entry points are not limited to the top-level.

  24. OK Now, let's write.

  25. Step 1. • Write down all your ideas • Highlight

    what matter the most • Write 2 to 5 lines for each point
  26. Go straitgh to the point. It's not a novel.

  27. And then… Repeat! And again! And again and again!

  28. Don't be afraid. Write first, organize later.

  29. Step 2. Organize.

  30. The overall experience is a non-linear reading. Yet, each bloc

    is still pretty linear.
  31. First level are documentation type. These are the where you

    separate readers by their usage.
  32. Example of first-level entry points

  33. Second level is a topic-based organisation. This is where you

    separate readers by needs.
  34. And below: where the content shines. Don't worry, you'll find

  35. When too big, repeat step 1 at the level you

    are - again.
  36. Personal content organization • Install • Configuration • Topics •

    Advanced topics • Dev-Guide / testing tools • Package reference (autodoc)

  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?
  39. Logging

  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)
  41. The problem is not the lack of content. There is

    just too much content. And it is not well organized.
  42. Readers's attention span is limited by the problem they want

    to solve.
  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
  44. So. (what did I say about digression?)

  45. Step 3. Standardize

  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
  47. Step 4 Ensure consistency

  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
  49. Assume readers don't know more than the current chapter.

  50. Also don't tell History. Unless you are Wikipedia.

  51. What's next?

  52. Good content explains why. It gives the intent hidden deep

    into the source code.
  53. Autodoc is not enough. It never tells the big picture.

  54. Just write. You'll be fine.

  55. Thanks! Question(s)?

  56. (bonus slide) https://commons.wikimedia.org/wiki/File:%22Sadness %22_from_Le_Brun,_Characters_des_passions,_circa_1720._Wellcome_L0010225.jpg