Download to read offline
Uploaded byLaura Novich
Documentation Communities: Sound Strategy or Documentarian's Gambit?
The document discusses ScyllaDB's transition from closed source to open source documentation. It outlines the challenges they faced, such as inconsistent documentation across repositories and lack of structure. Their solution involved adopting a common documentation framework across repositories using Sphinx and a universal theme. This provided version selection, templates, and automation. They now have a standardized workflow and are seeking more contributors to help document additional products.
![Vibe Coding vs. Spec-Driven Development [Free Meetup]](https://cdn.slidesharecdn.com/ss_thumbnails/vibecodingvsspecdrivendevelopment-251209105622-43f455e7-thumbnail.jpg?width=640&height=640&fit=bounds)
Documentation Communities: Sound Strategy or Documentarian's Gambit?
- 1. Documentation Communities: Sound Strategyor Documentarian’s Gambit? Laura Novich Senior Technical Writer ScyllaDB
- 2. What Will YouLearn? ▪ 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 OpenSource 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) ▪ Suiteof 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 AlreadyHad ▪ 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 WereMissing ▪ Structure ▪ Governance & Guidelines ▪ Single Source of Truth (SSOT) ▪ Total buy-in ▪ Reward system ▪ A bird’s eye view
- 11. The Challenge ▪ Releaseschedule ▪ Documentation quality ▪ Issues (bug fixes) ▪ New Knowledge Base Articles
- 12. ▪ Long closecycle for doc bugs ▪ Many cooks, few chefs ▪ But it works, right? Looks Can be Deceiving
- 13. The Gambits “A gambitis 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 youCombat 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 DocsFranchise ▪ 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 Easyto 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 theDocs 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 Getthe C-suites on Board? ▪ Numbers / Analytics ▪ ROI ▪ Headcount ▪ Run a pilot project
- 21. Reward, Reward, Reward ▪Meaningful ▪ Personal ▪ Consistent ▪ Global ▪ Tiered 21
- 22.
- 23. Keep Docs Closedor 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.
- 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 markuptext 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 ▪ CSSfor 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 Chosethis Solution ▪ Version Selection ▪ Maintainers wanted to help ▪ Smaller chunks of content ▪ Minimal change from the user’s perspective ▪ Fast turnaround time
- 31. Where are WeNow? 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 WeStill 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 DoWe Still Have? ▪ No CCMS ▪ No integration with Training and Marketing ▪ Need more contributors to Scylla and Scylla Docs
- 34. Want to JoinUs? ▪ 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 yourturn: Questions? Comments?
- 36. Thank You Laura Novich Email:laura@scylladb.com
- 37.