From 480fcd4ae585d4d5880c230fa0ce9dcfe9f4ba7e Mon Sep 17 00:00:00 2001 From: Nicolai Ort Date: Thu, 21 Mar 2024 17:00:27 +0100 Subject: [PATCH] more day 3 talks --- content/day3/03_oss_business_value.md | 80 ++++++++++++++++++++++++++ content/day3/04_towards_great_docs.md | 75 ++++++++++++++++++++++++ content/lessons_learned/99_checkout.md | 1 + 3 files changed, 156 insertions(+) create mode 100644 content/day3/03_oss_business_value.md create mode 100644 content/day3/04_towards_great_docs.md diff --git a/content/day3/03_oss_business_value.md b/content/day3/03_oss_business_value.md new file mode 100644 index 0000000..d83358c --- /dev/null +++ b/content/day3/03_oss_business_value.md @@ -0,0 +1,80 @@ +--- +title: Why is this so hard! Conveying the business value of open source +weight: 3 +--- + +Bob a Program Manager at Google and Kubernetes steering commitee member with a bunch of contributor and maintainer experience. +The value should be rated even higher than the pure business value. + +## Baseline + +* A öarge chunk of CNCF contrinbutors and maintainers (95%) are company affiliated +* Most (50%) of the people contributed in professional an personal time )(and 30 only on work time) +* Explaining business value can be very complex +* Base question: What does this contribute to the business + +## Data enablement + +* Problem: Insufficient data (data collection is often an afterthought) +* Example used: Random CNCF slection + * 50% of issues are labed consistentöy + * 17% of projects label PRs + * 58% of projects use milestones +* Labels provide: Context, Prioritization, Scope, State +* Milestones enable: Filtering outside of daterange +* Sample queries: + * How many features have been in milestone XY? + * How many bugs have been fixed in this version? + * What have I/my team worked on over time? + +### Triage + +* Many projects don't triage b/C + * Auth (No Role that can only edit labels+milestones) + * Thought of as overhead + * Project is too small +* Tools: + * Actions/Pipelines for autolabel, copy label sync labels + * Prow: The label system for kubernetes projects +* People with high project but low code knowlege can triage -> Make them feel recognized + +### Conclusions + +* Consistent labels & milestones are critical for state analysis +* Data is the evidence needed in messaging for leadershiü +* Recruting triage-specific people and using automations streamlines the process + +## Communication + +### Personas + +* OSS enthusiast: Knows the ecosystem and project with a knack for discussions and deep dives +* Maintainer;: A enthusiast that is tired, unter pressure and most of the time a one-man show that would prefer doint thechnical stuff +* CXO: Focus on ressources, health, ROI +* Product manager: Get the best project, user friendly +* Leads: Employees should meet KPIs, with slightly better techn understanding +* End user: How can tools/features help me + +### Growth limits + +* Main questions: + * What is theis project/feature + * Where is the roadmap + * What parts of the project are at risk? +* Problem: Wording + +### Ways of surfcing information + +* Regular project reports/blog posts +* Roadmap on website +* Project boards -> GitHub's feature for this is apparently pretty nice + +### Questions by leadership + +* What are we getting out? (How fast are bugs getting fixed) +* What is the criticality of the project? +* How much time is spent on maintainance? + +## Conclusion + +* Ther is significant unrealized valze in open source \ No newline at end of file diff --git a/content/day3/04_towards_great_docs.md b/content/day3/04_towards_great_docs.md new file mode 100644 index 0000000..a4d82aa --- /dev/null +++ b/content/day3/04_towards_great_docs.md @@ -0,0 +1,75 @@ +--- +title: "Towards Great Documentation: Behind a CNCF-Led Docs Audit" +weight: 4 +--- + +A talk about the backstage documentation audit and what makes a good documentation. + +## Opening + +* 2012 the year of the mayan calendar and the mainstream success of memes +* The classic meme RTFM -> Classic manuals were pretty long +* 2024: Manuals have become documentation (hopefully with better contents) + +## What gets us to good documentation + +### What is documentation + +* Docs (the raw descriptions, qucikstart and how-to) +* Website (the first impression - what does this do, why would i need it) +* REAMDE (the github way of website + docs) +* CONTRIBUTING (Is this a one-man show) +* Issues +* Meta docs (how do we orchestrate things) + +### Project documentation + +* Who needs this documentation? + * New users -> Optimize for minimum context + * Experienced users + * User roles (Admins, end users, ...) -> Seperate into different pages (Get started based in your role) +* What do we need to enable with this documentation? + * Prove value fast -> Why this project? + * Educate on fundemental aspects + * Showcase features/uses cases + * Hands-on enablement -> Tutorials, guides, step-by-step + +### Contributor documentation + +* Communication channels have to be clearly marked +* Documented scheduled contributor meetings +* Getting started guides for new contributors +* Project governance + * Who is gonna own it? + * What will happen to my PR? + * Who maintains features? + +### Website + +* Single source for all pages (one repo that includes landing, docs, api and so on) -> Easier to contribute +* Usability (especially on mobile) +* Social proof and case studies -> Develop trust +* SEO (actually get found) and analytics (detect how documentation is used and where people leave) +* Plan website maintenance + +### What is great documetnation + +* Project docs helps users according to their needs -> Low question to answer latency +* Contributor docs enables contributions in a predictable manner -> Don't leave "when will this be reviewed/mered" questions open +* Website proves why anyone should invest time in this projects? +* All documetnation is connected and up to date + +## General best practices + +* Insular pages: One page per topic, preferably short +* Include API reference +* Searchable +* Plan for versioning early on (the right framework is important) +* Plan for localization + +## Examples + +* Opentelemetry: Split by role (dev, ops) +* Prometheus: + * New user conent in intro (concept) and getting started (practice) + * Hierarchie includes concepts, key features and guides/tutorials \ No newline at end of file diff --git a/content/lessons_learned/99_checkout.md b/content/lessons_learned/99_checkout.md index 19f580e..ce4d42c 100644 --- a/content/lessons_learned/99_checkout.md +++ b/content/lessons_learned/99_checkout.md @@ -6,3 +6,4 @@ Just a loose list of stuff that souded interesting * Dapr * etcd backups +* Prow (labeling)