TL;DR: Can we create a minimum quality/relevance standard for examples in docs?
The issue:
To start with, documentation is pretty much a mess, with the rep reward drawing a large amount of useless edits and low-quality, low-relevance examples.
Unfortunately, not that much can be done about the low-quality edits, but we can set a community standard for the quality/relevance of examples.
To prove my point, I'll use the CSS Positioning docs as an example.
Low-quality:
I think we can all agree that this shouldn't be a thing:
- A minor sin, but all the box offset examples should be grouped together, instead of a separate example for each one(This is just my opinion).
- A user-specific JSFiddle example. If the user changes their name/deletes their account, the link breaks. Doesn't belong in docs.(Can we get snippets, pretty please?)
This makes my eyes scream. This makes baby unicorns cry blood. This puts you on Jon Skeet's naughty list. Here's why:
The initial problem you see is the entire text is a link, but that isn't actually an issue. One small edit, example fixed. The problem here is the users literally just copied the MDN docs on the property, and pasted them without giving any extra information.
Quoting external docs is fine. It can provide valuable information, as well as extra references. But if I wanted a MDN doc, I would have gone to the MDN page, and gotten a lot more info to boot.
Is posting like this acceptable? If not, can we have a community effort to stop approving examples like this?
Low-relevance:
People are going to be opinionated on whether examples like this should be removed or not, so I think a decision that can be referenced will help greatly with cleanup work.
The quality of the example is fairly decent, and it does provide an example relevant to the CSS positioning topic. The problem is, how relevant is relevant enough?
The issue I have with examples like this, is that when you add a example to address a specific issue that most people won't need/use, and is only loosely related to the the topic of the doc, you open the gates for really anything. We'll keep getting these examples, but they'll never be removed, because we have no standard that would justify removing them.
This is docs, not a tutorial blog. We don't need, or want, examples for every little creation anyone can think of, that will just end up with a bloated, unusable mess of random info that nobody cares about.
Summary:
I like the concept of docs, and I think it'll be a useful tool for many people. But nobody wants to use a dirty tool.
Can we please create a standard that we can reference when cleaning up docs, instead of being unsure of what should and should not be removed?
Can we please stop approving low-quality examples, simply because the topic needs examples?
Basically, docs is an asset for the community, and it's the community's responsibility to keep it clean. Please do your part.