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

FOSS DOCS 101 (keep it simple, present!)

FOSS DOCS 101 (keep it simple, present!)

WATCH THE VIDEO HERE: https://www.youtube.com/watch?v=FopnpwK6ALw

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.

Presented at EuroPython 2015: https://ep2015.europython.eu/conference/talks/foss-docs-101-keep-it-simple-present

thatdocslady

July 24, 2015
Tweet

More Decks by thatdocslady

Other Decks in Technology

Transcript

  1. FOSS DOCS 101
    Mikey Ariel
    Senior technical writer, Red Hat
    EuroPython, July 2015

    View full-size slide

  2. EuroPython 2015 | MIKEY ARIEL
    who am I?

    View full-size slide

  3. EuroPython 2015 | MIKEY ARIEL
    why am I here?

    View full-size slide

  4. EuroPython 2015 | MIKEY ARIEL
    documentation matters!
    (to me, to you, and you, and you...)

    View full-size slide

  5. EuroPython 2015 | MIKEY ARIEL
    times are a' changing...
    Documentation is a key component of
    successful software
    Documentation is an afterthought of
    software delivery

    View full-size slide

  6. EuroPython 2015 | MIKEY ARIEL
    how documentation helps
    Unified and intuitive
    user experience
    Portable and adoptable
    workflow
    Scalable and adaptable
    project

    View full-size slide

  7. EuroPython 2015 | MIKEY ARIEL
    join the docs club
    Content Strategy
    DevOps for Docs
    Community Engagement

    View full-size slide

  8. EuroPython 2015 | MIKEY ARIEL
    asking the right questions
    (even if the answer is as simple as 42)

    View full-size slide

  9. EuroPython 2015 | MIKEY ARIEL
    WHO
    are my readers?

    View full-size slide

  10. EuroPython 2015 | MIKEY ARIEL
    WHAT
    do my readers want to know?

    View full-size slide

  11. EuroPython 2015 | MIKEY ARIEL
    WHEN
    do my readers need this content?

    View full-size slide

  12. EuroPython 2015 | MIKEY ARIEL
    WHERE
    do my readers consume this content?

    View full-size slide

  13. EuroPython 2015 | MIKEY ARIEL
    WHY
    do my readers even need this content?

    View full-size slide

  14. EuroPython 2015 | MIKEY ARIEL
    GNOME help

    View full-size slide

  15. EuroPython 2015 | MIKEY ARIEL
    GNOME help

    View full-size slide

  16. EuroPython 2015 | MIKEY ARIEL
    GNOME help

    View full-size slide

  17. EuroPython 2015 | MIKEY ARIEL
    GNOME help

    View full-size slide

  18. EuroPython 2015 | MIKEY ARIEL
    GNOME help

    View full-size slide

  19. EuroPython 2015 | MIKEY ARIEL
    archlinux wiki

    View full-size slide

  20. EuroPython 2015 | MIKEY ARIEL
    archlinux wiki

    View full-size slide

  21. EuroPython 2015 | MIKEY ARIEL
    RHEL OpenStack

    View full-size slide

  22. EuroPython 2015 | MIKEY ARIEL
    RHEL OpenStack
    ???

    View full-size slide

  23. EuroPython 2015 | MIKEY ARIEL
    DevOps for Docs
    (not just for developers anymore!)

    View full-size slide

  24. EuroPython 2015 | MIKEY ARIEL
    DevOps
    for Docs
    continuous
    integration
    automation
    content
    curation
    iterative
    authoring
    unified
    toolchain

    View full-size slide

  25. EuroPython 2015 | MIKEY ARIEL
    docs or it didn't happen
    (even when nobody got time for that)

    View full-size slide

  26. EuroPython 2015 | MIKEY ARIEL

    View full-size slide

  27. EuroPython 2015 | MIKEY ARIEL
    contribution guidelines

    View full-size slide

  28. EuroPython 2015 | MIKEY ARIEL
    NixOS

    View full-size slide

  29. EuroPython 2015 | MIKEY ARIEL
    templates

    View full-size slide

  30. EuroPython 2015 | MIKEY ARIEL
    Read the Docs

    View full-size slide

  31. EuroPython 2015 | MIKEY ARIEL
    collaboration and training

    View full-size slide

  32. EuroPython 2015 | MIKEY ARIEL
    sprints and hackfests

    View full-size slide

  33. EuroPython 2015 | MIKEY ARIEL
    conferences and communities

    View full-size slide

  34. EuroPython 2015 | MIKEY ARIEL
    welcome to the club!

    View full-size slide