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

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)
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