FOSS DOCS 101

FOSS DOCS 101

Does your open source project need better documentation? Do you wish that new users could get started with your software more easily? Do you feel that your code contribution workflow isn’t documented well enough, or that contributors are discouraged from documenting their code? How can you give your project docs the love they deserve?

This high-level talk aims to introduce the main principles of technical communication in the context of FOSS projects. It is intended for anyone who interacts with documentation, whether your project is fresh off the dev environment or has been around since the dawn of Git. Topics include content strategy and planning, infrastructure and information management, and community contribution and engagement.

This deck reflects the presentation as delivered at Django Under the Hood 2015 conference: https://public.pad.fsfe.org/p/docs-under-the-hood-workshop

Cc4eb61ea6ff5b734785c6fc6c4be305?s=128

thatdocslady

November 07, 2015
Tweet

Transcript

  1. Mikey Ariel Mikey Ariel @ThatDocsLady | @WriteTheDocs @ThatDocsLady | @WriteTheDocs

    Django Under the Hood, November 2015 Django Under the Hood, November 2015 FOSS DOCS 101 FOSS DOCS 101
  2. who am I?

  3. why am I here?

  4. documentation matters! (to me, to you, and you, and you...)

  5. times are a' changing... Documentation is a key component of

    successful software Documentation is an afterthought of software delivery
  6. how documentation helps Unified and intuitive user experience Portable and

    adoptable workflow Scalable and adaptable project
  7. join the docs club Content Strategy DevOps for Docs Community

    Engagement
  8. asking the right questions (even if the answer is as

    simple as 42)
  9. WHO are my readers?

  10. WHAT do my readers want to know?

  11. WHEN do my readers need this content?

  12. WHERE do my readers consume this content?

  13. WHY do my readers even need this content?

  14. GNOME help

  15. GNOME help

  16. GNOME help

  17. GNOME help

  18. GNOME help

  19. archlinux wiki

  20. archlinux wiki

  21. archlinux wiki

  22. RHEL OpenStack

  23. before...

  24. before...

  25. before...

  26. before... ???

  27. … after!

  28. … after!

  29. … after!

  30. DevOps for Docs (not just for developers anymore!)

  31. DevOps for Docs unified toolchain

  32. universal platform

  33. standardized review flow

  34. live preview

  35. out-of-the-box publication

  36. DevOps for Docs continuous integration unified toolchain

  37. automatic builds

  38. continuous staging

  39. DevOps for Docs continuous integration automation unified toolchain

  40. sanity checks

  41. unit tests

  42. DevOps for Docs continuous integration Iterative authoring automation unified toolchain

  43. before...

  44. … after!

  45. … after!

  46. … after!

  47. DevOps for Docs continuous integration Iterative authoring collaboration automation unified

    toolchain
  48. we're all in this together Designers Developers Product Managers Quality

    Assurance Support Engineers Users
  49. docs or it didn't happen (even when nobody got time

    for that)
  50. None
  51. contribution guidelines

  52. docs as a development requirement django project linux kernel OpenStack

  53. NixOS

  54. templates

  55. Read the Docs

  56. collaboration and training

  57. sprints and hackfests

  58. conferences and communities

  59. welcome to the club!

  60. THANK YOU! THANK YOU! mariel@redhat.com mariel@redhat.com @ThatDocsLady @ThatDocsLady @WriteTheDocs @WriteTheDocs