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
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?
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 out.
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)
37. WARNING
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