Pro Yearly is on sale from $80 to $50! »

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

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/

Cc4eb61ea6ff5b734785c6fc6c4be305?s=128

thatdocslady

April 11, 2019
Tweet

Transcript

  1. DOCS OR IT DIDN’T HAPPEN! (with Q&A) Mikey Ariel @ThatDocsLady

    @WriteTheDocs DjangoCon Europe, April 2019
  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 ◉ <something> is stopping us from working on docs
  3. Who is That Docs Lady? @ThatDocsLady docs@docsideofthemoon.com @WriteTheDocs

  4. WHAT’S ON THE MENU TODAY?

  5. Content Strategy Plan a little, save a lot

  6. Content Strategy Plan a little, save a lot DevOps for

    Docs Not just for developers anymore
  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
  8. JOIN THE DOCUMENTARIAN CLUB!

  9. “ “A documentarian is someone who cares about documentation and

    communication in the software industry, regardless of job title.” http://www.writethedocs.org/documentarians/
  10. Community Writers DevOps Testers Designers Marketing Developers Support DOCUMENTARIANS

  11. CONTENT STRATEGY Asking the right questions in advance can save

    a lot of time later 1
  12. NEED-TO-KNOW DOCS (and no, you don’t need to know everything)

  13. Need-to-Know Documentation

  14. Why Need-to-Know Documentation

  15. Goal-Oriented Docs

  16. Why Who Need-to-Know Documentation

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

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

  19. Why What Who Need-to-Know Documentation

  20. Minishift README github.com/minishift/minishift

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

  22. Arch Linux Wiki wiki.archlinux.org

  23. Arch Linux Wiki wiki.archlinux.org

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

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

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

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

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

  29. DEVOPS FOR DOCS Let’s geek out about processes, tools, and

    workflows, oh my! 2
  30. INTEGRATION If you can’t beat them, join them!

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

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

  33. Issue Tracking github.com/minishift/minishift

  34. Issue Tracking github.com/minishift/minishift

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

  36. Publication Tools

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

  38. Live-Preview Staging github.com/writethedocs/www/pulls/<YOUR-PR-HERE>

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

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

  41. Linguistic Validation www.hemingwayapp.com

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

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

    each other 3
  44. “ Docs or it didn’t happen! - Me, at the

    beginning of this presentation
  45. Django Project Linux Kernel OpenStack Documentation as a Deliverable

  46. Contribution Guides nixos.wiki/wiki/Contributing_to_Nix_documentation

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

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

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

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

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

  52. Meet and greet more Documentarians!

  53. Write the Docs

  54. Doc-to-Dev Outreach Find me for a chat at the conference!

    (I have stickers)
  55. Season of Docs developers.google.com/season-of-docs

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

  57. Grammar, Syntax, and Linguistics 1

  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?”
  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!
  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."
  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.”
  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.”
  63. Collaboration, Contributions, and Community 2

  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?”
  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?”
  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?”
  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?”
  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!
  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?”
  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
  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
  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
  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
  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
  75. MOAR #QUESTIONS? (remember to ask responsibly) (I’ll also be available

    for 1:1 questions later)
  76. @ThatDocsLady docs@docsideofthemoon.com @WriteTheDocs LET’S WRITE SOME DOCS!