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

Transcript

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

   View Slide

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
   

   View Slide

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

   View Slide

4. View Slide

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

   View Slide

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!
   

   View Slide

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.
   

   View Slide

8. … it's bad for everyone.
   

   View Slide

9. What is
   documentation
   

   View Slide

10. This is where we explain things for humans.
    But wait.
    What kind of documentation?
    

    View Slide

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!
    

    View Slide

12. (also skill levels)
    

    View Slide

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

    View Slide

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

    View Slide

15. OK GOOD.
    HOW?
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

20. Problem: story is linear.
    Solution: entry points are not.
    

    View Slide

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

    View Slide

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.
    

    View Slide

23. Entry points are not limited to the top-level.
    

    View Slide

24. OK Now, let's write.
    

    View Slide

25. Step 1.
    ●
    Write down all your ideas
    ●
    Highlight what matter the most
    ●
    Write 2 to 5 lines for each point
    

    View Slide

26. Go straitgh to the point.
    It's not a novel.
    

    View Slide

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

    View Slide

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

    View Slide

29. Step 2.
    Organize.
    

    View Slide

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

    View Slide

31. First level are documentation type.
    These are the where you separate readers by their usage.
    

    View Slide

32. Example of first-level entry points
    

    View Slide

33. Second level is a topic-based organisation.
    This is where you separate readers by needs.
    

    View Slide

34. And below: where the content shines.
    Don't worry, you'll find out.
    

    View Slide

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

    View Slide

36. Personal content organization
    ●
    Install
    ●
    Configuration
    ●
    Topics
    ●
    Advanced topics
    ●
    Dev-Guide / testing tools
    ●
    Package reference (autodoc)
    

    View Slide

37. WARNING
    

    View Slide

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?
    

    View Slide

39. Logging
    

    View Slide

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)
    

    View Slide

41. The problem is not the lack of content.
    There is just too much content.
    And it is not well organized.
    

    View Slide

42. Readers's attention span is
    limited by the problem
    they want to solve.
    

    View Slide

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
    

    View Slide

44. So.
    (what did I say about digression?)
    

    View Slide

45. Step 3.
    Standardize
    

    View Slide

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
    

    View Slide

47. Step 4
    Ensure consistency
    

    View Slide

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
    

    View Slide

49. Assume readers don't know
    more than the current chapter.
    

    View Slide

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

    View Slide

51. What's next?
    

    View Slide

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

    View Slide

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

    View Slide

54. Just write. You'll be fine.
    

    View Slide

55. Thanks!
    Question(s)?
    

    View Slide

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

    View Slide