Docs or it didn't happen! [DjangoCon Europe 2019]

**This special edition of the talk was given at DjangoCon Europe 2019 in Copenhagen and includes a Q&A section**

Have you ever skimmed through a README, tried to follow a quickstart tutorial, attempted to decipher an error message, or typed '--help' in your console? Congratulations -- you have encountered documentation! Long gone are the days of massive books with never-ending stories about your software. Today's users are smarter and less patient, which means that we no longer need to document all the things, as long as what we do document is clear, concise, helpful, and accessible. And that's where the real work starts.

Documentation requires some attitude adjustment, since prose doesn't neatly compile into binaries as code does. But Don't Panic(tm)! No matter what your role is in the community, you can apply a few key principles from the technical writing world to make your project more docs-friendly, and therefore more user- and contributor-friendly.

This talk covers strategies, best practices, and pro tips for rethinking how we create and curate documentation. This special edition will include Django-specific examples and use-cases as well as a special Q&A session, where we will try to address some of the community's top concerns and ideas about the Django docs.

https://members.2019.djangocon.eu/conference/talk/BHV8UW/

Transcript

1. DOCS OR IT DIDN’T HAPPEN!
   (with Q&A)
   Mikey Ariel
   @ThatDocsLady @WriteTheDocs
   DjangoCon Europe, April 2019
   

   View Slide

2. Why are we here?
   The Q&A section will include first questions that were collected in advance from Twitter, and then questions collected
   during the talk from Slack and moderated by the host. Please ask responsibly!
   If you have a question or need some help with your documentation, please come and find me during the conference! You
   can also email, Slack, or tweet @ThatDocsLady with your questions any time.
   ◉ We want to have more users and contributors
   ◉ We believe (or want to believe) that docs can help
   ◉ is stopping us from working on docs
   

   View Slide

3. Who is That Docs Lady?
   @ThatDocsLady docs@docsideofthemoon.com @WriteTheDocs
   

   View Slide

4. WHAT’S ON THE MENU TODAY?
   

   View Slide

5. Content Strategy
   Plan a little, save a lot
   

   View Slide

6. Content Strategy
   Plan a little, save a lot
   DevOps for Docs
   Not just for developers anymore
   

   View Slide

7. Content Strategy
   Plan a little, save a lot
   Community Spirit
   We’re all in this together
   DevOps for Docs
   Not just for developers anymore
   

   View Slide

8. JOIN THE DOCUMENTARIAN CLUB!
   

   View Slide

9. “
   “A documentarian is someone who
   cares about documentation and
   communication in the software
   industry, regardless of job title.”
   http://www.writethedocs.org/documentarians/
   

   View Slide

10. Community
    Writers
    DevOps Testers
    Designers
    Marketing
    Developers
    Support
    DOCUMENTARIANS
    

    View Slide

11. CONTENT STRATEGY
    Asking the right questions in advance can save a lot of time later
    1
    

    View Slide

12. NEED-TO-KNOW DOCS
    (and no, you don’t need to know everything)
    

    View Slide

13. Need-to-Know Documentation
    

    View Slide

14. Why
    Need-to-Know Documentation
    

    View Slide

15. Goal-Oriented Docs
    

    View Slide

16. Why Who
    Need-to-Know Documentation
    

    View Slide

17. GNOME Help
    help.gnome.org
    help.gnome.org
    

    View Slide

18. GNOME Help
    help.gnome.org
    Users
    Developers
    Administrators
    

    View Slide

19. Why What
    Who
    Need-to-Know Documentation
    

    View Slide

20. Minishift README
    github.com/minishift/minishift
    

    View Slide

21. Why When
    What
    Who
    Need-to-Know Documentation
    

    View Slide

22. Arch Linux Wiki
    wiki.archlinux.org
    

    View Slide

23. Arch Linux Wiki
    wiki.archlinux.org
    

    View Slide

24. Why Where
    When
    What
    Who
    Need-to-Know Documentation
    

    View Slide

25. Minishift Troubleshooting
    github.com/minishift/minishift/issues/1152
    

    View Slide

26. Minishift Troubleshooting
    github.com/minishift/minishift-centos-iso/pull/119
    

    View Slide

27. Minishift Troubleshooting
    docs.openshift.org/latest/minishift/troubleshooting/troubleshooting-misc
    

    View Slide

28. Why Where
    When
    What
    Who
    Need-to-Know Documentation
    

    View Slide

29. DEVOPS FOR DOCS
    Let’s geek out about processes, tools, and workflows, oh my!
    2
    

    View Slide

30. INTEGRATION
    If you can’t beat them, join them!
    

    View Slide

31. Docs-as-Code
    github.com/minishift/minishift
    

    View Slide

32. Hierarchical Source Content
    github.com/minishift/minishift
    

    View Slide

33. Issue Tracking
    github.com/minishift/minishift
    

    View Slide

34. Issue Tracking
    github.com/minishift/minishift
    

    View Slide

35. CONTINUOUS PUBLICATION
    No need to stop the press anymore!
    

    View Slide

36. Publication Tools
    

    View Slide

37. Continuous Deployment
    readthedocs.org/projects/writethedocs-www/builds
    

    View Slide

38. Live-Preview Staging
    github.com/writethedocs/www/pulls/
    

    View Slide

39. TESTING AUTOMATION
    More than a just a spell-checker!
    

    View Slide

40. Code Blocks Validation
    github.com/endocode/shelldoc
    

    View Slide

41. Linguistic Validation
    www.hemingwayapp.com
    

    View Slide

42. Test Automation Framework
    github.com/emender/emender
    

    View Slide

43. COMMUNITY SPIRIT
    Let’s help our contributors help us and help each other
    3
    

    View Slide

44. “
    Docs or it didn’t happen!
    - Me, at the beginning of this presentation
    

    View Slide

45. Django Project
    Linux Kernel
    OpenStack
    Documentation as a Deliverable
    

    View Slide

46. Contribution Guides
    nixos.wiki/wiki/Contributing_to_Nix_documentation
    

    View Slide

47. Templates
    www.writethedocs.org/guide/writing/beginners-guide-to-docs
    

    View Slide

48. Modular Docs Project
    github.com/redhat-documentation/modular-docs
    

    View Slide

49. Modular Docs Project
    redhat-documentation.github.io/modular-docs
    

    View Slide

50. Modular Docs Project
    github.com/redhat-documentation/modular-docs/tree/master/modular-docs-manual/files
    

    View Slide

51. Modular Docs Project
    [...]/modular-docs-manual/filesTEMPLATE_PROCEDURE_doing-one-procedure.adoc
    

    View Slide

52. Meet and greet more
    Documentarians!
    

    View Slide

53. Write the Docs
    

    View Slide

54. Doc-to-Dev Outreach
    Find me for a chat at the conference!
    (I have stickers)
    

    View Slide

55. Season of Docs
    developers.google.com/season-of-docs
    

    View Slide

56. Q&A
    Crowdsourced, anonymized, and non-weaponized questions
    4
    

    View Slide

57. Grammar, Syntax, and Linguistics
    1
    

    View Slide

58. Grammar, Syntax, and Linguistics
    1
    “Do you see benefits in using/avoiding pronouns in docs? "Property x allows you
    to do y" vs "Property x allows for doing y". Do you have recommendations on
    when which version makes more sense or is more appropriate?”
    

    View Slide

59. Grammar, Syntax, and Linguistics
    1
    “Do you see benefits in using/avoiding pronouns in docs? "Property x allows you
    to do y" vs "Property x allows for doing y". Do you have recommendations on
    when which version makes more sense or is more appropriate?”
    MINIMALISM!
    

    View Slide

60. Grammar, Syntax, and Linguistics
    1
    "Property x allows you to do y."
    "Property x allows for doing y."
    "With X one can do Y."
    "With X doing Y is possible."
    "With X it's possible to do Y."
    

    View Slide

61. Grammar, Syntax, and Linguistics
    1
    "Property x allows you to do y."
    "Property x allows for doing y."
    "With X one can do Y."
    "With X doing Y is possible."
    "With X it's possible to do Y."
    “You do X with Y.”
    

    View Slide

62. Grammar, Syntax, and Linguistics
    1
    "Property x allows you to do y."
    "Property x allows for doing y."
    "With X one can do Y."
    "With X doing Y is possible."
    "With X it's possible to do Y."
    ● 2nd voice (“you”) in the relevant context (persona-based docs)
    ● “Things” cannot “allow” humans to do things (anthropomorphism)
    ● Active voice indicates goal first and method second (goal-oriented wording)
    ● Gerunds (“*ing”) are grammatically ambiguous and hard to translate
    “You do X with Y.”
    

    View Slide

63. Collaboration, Contributions, and Community
    2
    

    View Slide

64. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    

    View Slide

65. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    “When starting a project from scratch, how does one figure out how to structure the
    documentation and what are the first $n things one should take care of?”
    

    View Slide

66. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    “When starting a project from scratch, how does one figure out how to structure the
    documentation and what are the first $n things one should take care of?”
    “It’s very hard for someone to write documentation for a project if they don’t know how
    the project works. How do you best facilitate that knowledge transfer (other than, of
    course, writing docs…)? How do you bootstrap the process?”
    

    View Slide

67. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    “When starting a project from scratch, how does one figure out how to structure the
    documentation and what are the first $n things one should take care of?”
    “It’s very hard for someone to write documentation for a project if they don’t know how
    the project works. How do you best facilitate that knowledge transfer (other than, of
    course, writing docs…)? How do you bootstrap the process?”
    “I don't know what I don't know so how can I possibly know what you don't know?”
    

    View Slide

68. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    “When starting a project from scratch, how does one figure out how to structure the
    documentation and what are the first $n things one should take care of?”
    “It’s very hard for someone to write documentation for a project if they don’t know how
    the project works. How do you best facilitate that knowledge transfer (other than, of
    course, writing docs…)? How do you bootstrap the process?”
    “I don't know what I don't know so how can I possibly know what you don't know?”
    TALK TO PEOPLE!
    

    View Slide

69. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    

    View Slide

70. Collaboration, Contributions, and Community
    2
    “So I’ve got a project. I know I need docs. I can write, but I know it’s not my strength. What
    do I need to do to make it easier for someone who *does* have those skills to contribute?”
    ● Find people with writing experience and ask them to test your software, give you
    feedback, and help you build contribution guidelines
    ● Offer mentorship and fellowship to new contributors who can help you fix the docs
    but might not have programming experience (or experience with your project)
    ● Facilitate skill-sharing sprints or meetups where developers and writers can
    pair-work on documentation-related tasks
    

    View Slide

71. 2
    “When starting a project from scratch, how does one figure out how to structure the
    documentation and what are the first $n things one should take care of?”
    Collaboration, Contributions, and Community
    

    View Slide

72. 2
    “When starting a project from scratch, how does one figure out how to structure the
    documentation and what are the first $n things one should take care of?”
    ● Ask (potential) users what their workflow with your software is likely to be (day 0, 1,
    2, etc) and port that knowledge over to the docs (document the UX)
    ● Research best practices and templates (for example, modular docs project) and look
    up docs for projects that you like to study how they’re organized
    Collaboration, Contributions, and Community
    

    View Slide

73. 2
    “It’s very hard for someone to write documentation for a project if they don’t know how
    the project works. How do you best facilitate that knowledge transfer (other than, of
    course, writing docs…)? How do you bootstrap the process?”
    “I don't know what I don't know so how can I possibly know what you don't know?”
    Collaboration, Contributions, and Community
    

    View Slide

74. 2
    “It’s very hard for someone to write documentation for a project if they don’t know how
    the project works. How do you best facilitate that knowledge transfer (other than, of
    course, writing docs…)? How do you bootstrap the process?”
    “I don't know what I don't know so how can I possibly know what you don't know?”
    ● Accepting that you have a problem is the first step in solving the problem
    ● Reach out to your peers, make yourself available for training and mentorship, and
    be kind to people who want to contribute (welcoming projects get more
    contributors!)
    ● Most writers don’t have a deeper understanding of how the code is written, but their
    strategic communication experience is what makes them great writers - respect
    that!
    Collaboration, Contributions, and Community
    

    View Slide

75. MOAR #QUESTIONS?
    (remember to ask responsibly)
    (I’ll also be available for 1:1 questions later)
    

    View Slide

76. @ThatDocsLady docs@docsideofthemoon.com @WriteTheDocs
    LET’S WRITE SOME DOCS!
    

    View Slide