Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

thatdocslady

November 07, 2015
Tweet

More Decks by thatdocslady

Other Decks in Technology

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

    View Slide

  2. who am I?

    View Slide

  3. why am I here?

    View Slide

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

    View Slide

  5. times are a' changing...
    Documentation is a key component of
    successful software
    Documentation is an afterthought of
    software delivery

    View Slide

  6. how documentation helps
    Unified and intuitive
    user experience
    Portable and adoptable
    workflow
    Scalable and adaptable
    project

    View Slide

  7. join the docs club
    Content Strategy
    DevOps for Docs
    Community Engagement

    View Slide

  8. asking the right questions
    (even if the answer is as simple as 42)

    View Slide

  9. WHO
    are my readers?

    View Slide

  10. WHAT
    do my readers want to know?

    View Slide

  11. WHEN
    do my readers need this content?

    View Slide

  12. WHERE
    do my readers consume this content?

    View Slide

  13. WHY
    do my readers even need this content?

    View Slide

  14. GNOME help

    View Slide

  15. GNOME help

    View Slide

  16. GNOME help

    View Slide

  17. GNOME help

    View Slide

  18. GNOME help

    View Slide

  19. archlinux wiki

    View Slide

  20. archlinux wiki

    View Slide

  21. archlinux wiki

    View Slide

  22. RHEL OpenStack

    View Slide

  23. before...

    View Slide

  24. before...

    View Slide

  25. before...

    View Slide

  26. before...
    ???

    View Slide

  27. … after!

    View Slide

  28. … after!

    View Slide

  29. … after!

    View Slide

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

    View Slide

  31. DevOps
    for Docs
    unified
    toolchain

    View Slide

  32. universal platform

    View Slide

  33. standardized review flow

    View Slide

  34. live preview

    View Slide

  35. out-of-the-box publication

    View Slide

  36. DevOps
    for Docs
    continuous
    integration
    unified
    toolchain

    View Slide

  37. automatic builds

    View Slide

  38. continuous staging

    View Slide

  39. DevOps
    for Docs
    continuous
    integration
    automation
    unified
    toolchain

    View Slide

  40. sanity checks

    View Slide

  41. unit tests

    View Slide

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

    View Slide

  43. before...

    View Slide

  44. … after!

    View Slide

  45. … after!

    View Slide

  46. … after!

    View Slide

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

    View Slide

  48. we're all in this together
    Designers
    Developers
    Product Managers
    Quality Assurance
    Support Engineers
    Users

    View Slide

  49. docs or it didn't happen
    (even when nobody got time for that)

    View Slide

  50. View Slide

  51. contribution guidelines

    View Slide

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

    View Slide

  53. NixOS

    View Slide

  54. templates

    View Slide

  55. Read the Docs

    View Slide

  56. collaboration and training

    View Slide

  57. sprints and hackfests

    View Slide

  58. conferences and communities

    View Slide

  59. welcome to the club!

    View Slide

  60. THANK YOU!
    THANK YOU!
    [email protected]
    [email protected]
    @ThatDocsLady
    @ThatDocsLady
    @WriteTheDocs
    @WriteTheDocs

    View Slide