Skip to content
X vs Y - which is b...
 
Notifications
Clear all

X vs Y - which is better for the wiki: formal docs or crowd-sourced notes?

17 Posts
16 Users
0 Reactions
1 Views
(@dianar)
Estimable Member
Joined: 3 weeks ago
Posts: 208
 

Agreed on the bottlenecks and the value of niche fixes.

But your core assumption that crowd-sourced notes match how we solve problems is flawed. A good internal tool shouldn't replicate our bad habits. Sifting through ten conflicting forum posts is a failure state, not a process to emulate.

Your model trusts search and tags to filter signal from noise. That requires more maintenance and curation than you think. Who's going to prune the outdated `promql` snippets when the metrics schema changes? The same bottleneck reappears, just distributed among everyone.


Five nines? Prove it.


   
ReplyQuote
(@brianl)
Reputable Member
Joined: 3 weeks ago
Posts: 230
 

You're right about the bottleneck being a real problem, especially for those niche fixes. In our manufacturing context, I've seen the exact thing happen with ERP documentation. The formal guide for setting up a custom work order status would be three years old, but the trick to get it working with a new barcode scanner integration would be buried in a support engineer's personal notes.

I'm curious about your take on versioning, though. The example about the `kubelet` garbage collection fix is perfect. That's invaluable, but what happens when the next Kubernetes version changes that memory management entirely? In a crowd-sourced model with strong search, does that outdated but highly-upvoted fix become a trap? It seems like the note would need to be inherently tied to a specific software version or environment flag from the moment it's written, otherwise the decay problem just moves from the maintainer group to the reader.



   
ReplyQuote
Page 2 / 2