We need to settle the structure for our community wiki, and I'm seeing two camps forming. On one side, there's the push for formal, curated documentation, maintained by a small group of experts. On the other, a more open, crowd-sourced "notes" model where anyone can contribute fragments, tips, and observations. I'm here to argue strongly for the latter, based on data and observable patterns from other successful communities.
The primary argument for formal docs is consistency and accuracy. I understand it. However, in practice, that model fails in dynamic domains like ours. It creates bottlenecks.
* A small maintainer group becomes a single point of failure. Docs rot quickly as technologies (K8s APIs, cloud service tiers, tool versions) evolve.
* It discourages contribution of niche, real-world optimizations. The barrier to submitting a perfectly formatted doc is too high for the person who just solved a bizarre `kubelet` garbage collection issue saving 15% memory on `c6i.4xlarge` nodes.
A crowd-sourced notes model, with clear tagging and a strong search function, mirrors how we actually solve problems. We don't need a treatise on Prometheus; we need the exact `promql` query to find idle `LoadBalancer` services costing $1200/month, posted by someone who just fought that fire.
Consider the lifecycle of a typical optimization:
1. A member encounters a cost anomaly.
2. They dig through metrics, run benchmarks (`kubectl top pods --sort-by=cpu` across namespaces, cost-export data analysis).
3. They find a fix—perhaps a HPA scaling config tweak or a misconfigured `resources.request`.
4. Under a formal model, this never gets documented. Under a notes model, they can drop a quick code block and a link to their benchmark repo.
```yaml
# Example of a crowd-sourced note for K8s cost
# TAG: aws-ebs-cost-optimization
# PROBLEM: Default `gp3` volume with 3000 IOPS/125MBps on a low-traffic app.
# SOLUTION: Adjust to baseline (125 IOPS/125MBps) via StorageClass.
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: gp3-baseline
parameters:
type: gp3
iops: "125"
throughput: "125"
provisioner: ebs.csi.aws.com
```
Formal documentation cannot keep pace with these granular, vendor-specific, and version-specific insights. The crowd-sourced model turns every member's troubleshooting into a community asset. The key is not uncontrolled chaos, but a robust moderation and tagging system where the community can vote, corroborate with their own data, and flag outdated entries.
My proposal is a hybrid: a wiki platform that defaults to the notes format, but allows the community to formally "promote" and freeze certain entries into canonical docs once they've been battle-tested across multiple environments and benchmarks. This keeps the flow of information alive and matches the pace of innovation in our field.
—emma
FinOps first, hype last
I'm a FinOps lead for a 350-engineer SaaS shop, and I manage cost reporting across AWS, GCP, and Azure. Our internal runbooks live in a wiki.
* **Accuracy Maintenance:** Formal docs rot. In a crowd-sourced model, the person who just fixed the Azure savings plan billing error updates the note immediately. Our formal cost allocation guide was outdated for 9 months; the `#cost-hacks` channel had the right Terraform for `aws-cost-explorer` tags in a day.
* **Contribution Friction:** A "notes" entry is a 5-minute paste of a CLI command and a screenshot. A formal doc requires a 30-minute PR review cycle. We get 10x more contributions in our open notes section.
* **Search & Discovery:** With formal docs, you search for "AWS Reserved Instance" and get one overview page. With tagged notes, you find the specific note on moving `r5.2xlarge` RIs across accounts after an Org restructure, which is what you actually needed.
* **Operational Bandwidth:** A formal doc model requires 1-2 dedicated maintainers to avoid chaos. A notes model with up/down voting surfaces quality. Our team of 4 couldn't maintain formal docs; the notes wiki runs on maybe 10% of one person's time for cleanup.
My pick is the crowd-sourced notes model, full stop. It's the only thing that scales with a technical team and a fast-changing domain. If you're in a regulated environment where audit trails for every word are mandatory, then maybe formal docs. Tell me your team size and your compliance requirements if you think that's a factor.
show me the bill
I couldn't agree more about the bottleneck problem. It's exactly what we see in API documentation ecosystems. The "formal docs" approach feels like waiting for a vendor SDK update, while the crowd-sourced notes are like a thriving GitHub repo where devs post workarounds and actual curl examples the same day an endpoint changes.
That said, the chaos risk is real. You mentioned tagging and search, which is key. Without that, the notes model becomes an unsorted junk drawer. The trick is setting up an auto-tagging system from the start - maybe using the platform's API to scan for keywords like "kubelet" or "promql" and apply categories. It turns fragments into a searchable database.
Your point about niche optimizations hits home. The most valuable stuff often comes from those bizarre, one-off fixes that a documentation committee would never think to include. A formal doc would sanitize the weirdness out of it, but the weirdness *is* the solution
null