Documentation Communities: Sound Strategy or Documentarian's Gambit?
•
0 likes•208 views
Write the Docs Portland 2021
Recommended
Recommended
More Related Content
Similar to Documentation Communities: Sound Strategy or Documentarian's Gambit?
Similar to Documentation Communities: Sound Strategy or Documentarian's Gambit? (20)
Recently uploaded
Recently uploaded (20)
Documentation Communities: Sound Strategy or Documentarian's Gambit?
- 1. Documentation Communities: Sound Strategy or Documentarian’s Gambit? Laura Novich Senior Technical Writer ScyllaDB
- 2. What Will You Learn? ▪ ScyllaDB’s journey from closed to open source documentation ▪ Items we considered ▪ What our solution included ▪ Where we are now ▪ What do we have planned ▪ How you can help
- 3. Meet Laura ● ScyllaDB: Senior Technical Writer ● Write the Docs: member ● OSS Documentarian & Mentor ● Instructor @ OBW ● Baking & Netflix No Spoilers!!!
- 4. Who Has Open Source Docs? ▪ GitLab, always was open ▪ Microsoft ▪ Docker ▪ Red Hat, no but Fedora is ▪ GitHub - as of October 2020 ▪ Anyone here? Let it be known!
- 5. ScyllaDB (sill-ah) ▪ Suite of products for all types of deployment (cloud, on-prem) • Enterprise and open-source products • Management and Monitoring tools • Several Drivers ▪ Offices in Herzliya, San Francisco, and Warsaw ▪ Developers all over the world ▪ We are Hiring!!!
- 7. What We Already Had ▪ An open-source product ▪ Many repositories ▪ A few contributors to code ▪ Multiple locations for information ▪ Some developers on-board
- 8. We Also Had ▪ Management on-board ▪ Many references to the docs ▪ Many visitors to the docs website ▪ Support tickets citing errors in the docs ▪ Open-source documentation tool chain ▪ Massive expansion in development
- 9. What We Wanted ▪ Total commitment ▪ Version selection ▪ More contributors ▪ Maintainer responsibility ▪ Automation
- 10. What We Were Missing ▪ Structure ▪ Governance & Guidelines ▪ Single Source of Truth (SSOT) ▪ Total buy-in ▪ Reward system ▪ A bird’s eye view
- 11. The Challenge ▪ Release schedule ▪ Documentation quality ▪ Issues (bug fixes) ▪ New Knowledge Base Articles
- 12. ▪ Long close cycle for doc bugs ▪ Many cooks, few chefs ▪ But it works, right? Looks Can be Deceiving
- 13. The Gambits “A gambit is a chess opening move where the player, usually White, sacrifices a piece with the aim of achieving a subsequent positional advantage. “ - Wikipedia
- 14. Potential Gambits ▪ Apathy ▪ Lack of engagement ▪ Leadership not on-board ▪ Developers refuse to comply ▪ Community contribution is poor ▪ Documentation quality is poor ▪ Time is wasted
- 15. How do you Combat the Gambits? ▪ Useful, meaningful, & predictable structure ▪ Easy to contribute ▪ Self-service check before check-in ▪ Be kind and thankful when you review ▪ Get everyone on board, especially management ▪ Reward, reward, reward
- 16. Create a Docs Franchise ▪ Every /docs directory has similar hierarchy and structure ▪ Content reuse ▪ Every document type has a template ▪ One CSS / Style guide to rule them all
- 17. Make it Easy to Contribute Documentation Easy Fix Help Needed ▪ Icons which push for contributions ▪ Every repository has a README ▪ Annotate code ▪ Git tags ▪ Slack - just for docs ▪ WTD Writing Days
- 18. Review with Care ▪ Answer all communication ▪ Timely reviews ▪ In-line review ▪ Constructive criticism ▪ Be kind and supportive ▪ Never assume contributors know ▪ Thank them!
- 19. All Aboard the Docs Train ▪ Find your friends of the docs ▪ Build your bridges of communication ▪ Start the docs talk early in the dev cycle ▪ Docs as part of feature development ▪ Docs as part of the sprint ▪ “It’s not done until it’s documented”
- 20. How to Get the C-suites on Board? ▪ Numbers / Analytics ▪ ROI ▪ Headcount ▪ Run a pilot project
- 21. Reward, Reward, Reward ▪ Meaningful ▪ Personal ▪ Consistent ▪ Global ▪ Tiered 21
- 23. Keep Docs Closed or Go Open ▪ Keep em Closed! • Maintain control of quality and contribution • Only TCs can write the docs ▪ Go Open! • Attract more people who want to help • More testing of docs • More tasks get done
- 24. Our Solution
- 25. What We Considered ▪ Different tool chain ▪ Hiring more writers ▪ Hiring a freelance developer ▪ Interns
- 26. What We Decided ▪ Docs in Tree ▪ Universal Theme ▪ Multiversion Selection ▪ Templates & Style Guide ▪ Automation ▪ Redesign of the Website and CSS
- 27. Our Workflow & Tool Chain Write Docs in Restructured Text or Markdown Using either templates or cheat sheets, create content in Markdown or Restructured Text. Test /Compile with Sphinx Test rendering with Sphinx Python scripts. View entire website in a sandbox environment. Push to GitHub Send all content changes as Pull Requests Report issues with GitHub At the bottom of every page, report issues using the “Report an Issue on this page” button. Deploy with GitHub Pages When ready, deploy the website content. 05 01 02 03 04
- 28. Sphinx ▪ Turns markup text into HTML. ▪ Linter for documentation. ▪ Directives: Extend restructuredText (e.g. display cards). ▪ Extensions: Add custom features (e.g. multi version support, copy button, custom theme). ▪ More Information - here
- 29. Sphinx Theme ▪ CSS for the Scylla Docs site ▪ All projects that have docs use the same theme ▪ Contains custom extensions and scripts shared between documentation projects sphinx-theme.scylladb.com
- 30. Why We Chose this Solution ▪ Version Selection ▪ Maintainers wanted to help ▪ Smaller chunks of content ▪ Minimal change from the user’s perspective ▪ Fast turnaround time
- 31. Where are We Now? 1. Implement a feedback button 2. Scylla Docs MVD Program 3. Driver pilot project 4. Write Style Guide, Templates, and Contribution Pages 5. Migrate remaining projects 6. Implement new Website and new Theme
- 32. What Do We Still Need to Do? 1. Enterprise, OSS, & Cloud 2. Formally announce our efforts 3. Implement New CSS / Theme & Maintenance 4. A/B Test and Survey 5. Celebrate?
- 33. What Gambits Do We Still Have? ▪ No CCMS ▪ No integration with Training and Marketing ▪ Need more contributors to Scylla and Scylla Docs
- 34. Want to Join Us? ▪ Contribute today! ▪ GSOD - We applied to be an organization ▪ laura@scylladb.com - let me know how you want to help ▪ Join the ScyllaDB Users Slack channel and the #scylla-docs channel Hello, is it YOU we’re looking for?
- 35. Now it’s your turn: Questions? Comments?
- 36. Thank You Laura Novich Email: laura@scylladb.com
- 37. Sea Monsters