I was reading yet another "Has Documentation Failed?" question, and came across this:
... most examples on Docs.SO are not "real-world code". They're artificial, used to explain a specific point.
This got me thinking: what if Documentation has this example thing the wrong way around.
What we have at the minute is collection of topics, each containing examples which demonstrate that topic.
An alternative is to have a collection of examples of code (a "repository", if you will), each tagged with a number of topics which apply to it, where code is voted on according to its quality.
I feel like this alternative would solve some of the major gripes with the existing Documentation platform:
Quality
- If you're going to use reputation as an incentive for documentation purposes, you have to make sure that it encourages useful forms of participation.
- I don't think it's possible to separate "bad" edits from "good" edits
- Should there be a way of checking that those approving edits have demonstrated at least some relevant knowledge?
- If this is collaboration, where we share the work, let us also share the reward, not multiply it.
This seems to be, by far, the most complained about problem with Documentation. Many users are writing "documentation" for the reputation, which has resulted in a lot of "I don't care what change I make, I just want reputation from this example forevermore" kind of edits. This sea of mediocrity is driving people away from making any meaningful contributions.
- People contribute to open source projects because they want to contribute towards a tangible, useful entity, not for internet points. There'd be no need for reputation rewards in this model, which should eliminate this sort of editing.
- With people invested in their projects, low quality checkins/pull requests would be rejected, because others will care about the quality of their code. Because low quality code will be rejected, we get the nice side effect of forcing people to demonstrate relevant knowledge in order to have an edit accepted.
- Having people voting on the quality of examples related to a topic gives a sort of low-level distributed code review, which should improve the quality again.
Plagiarism
This is largely driven by the reputation-seeking users mentioned above.
- Without reputation involved, this wouldn't be as widespread a problem.
- There are other, rather popular version control systems that seem to be doing alright for themselves, even with the potential for plagiarism.
Organisation
- Currently it just looks like a bunch of random topics
- Not only that. Go into a topic. What you see? 20 different topics
- Sometimes examples for tag could also be included in other tags
There's a very loose tree structure by Language/Framework/Library > Topic > Example as things stand. The main Q&A site uses an inverse system of Question > Tags, which works better for finding questions related to a topic. Using the Q&A system deals with the third bullet above straight away.
- Tagging code units in the repository uses the same system as the Q&A (and maybe even the same tags?) - examples can belong to multiple topics.
- You want to find code which demonstrates the use of dotnet-httpclient. You open a file in a project and find that several closely related topics are also demonstrated nearby, just because they often go together in real-world code.
- There's no way for "list of things" style topics to emerge - all the code found in a single place ought to be semantically related (in good quality code, at least).
Coherence
There's a distinct lack of agreement over what a Topic is, what an Example should show, what an up/downvote actually signifies. It's been about 20 months since Documentation was announced, and it doesn't seem to have coalesced into a coherent thing.
- A version control system is certainly a coherent idea
- I think that tagging examples of good code in that system to say "this is an example of how we used/did XXX in real code" would be at least a little more focussed than "here are some examples of XXX".
Downsides
I'm not totally delusional - I know there are sizeable issues in trying to get such a system off the ground. To name a few:
- There are a number of successful version control systems already: adding to a crowded marketplace isn't easy.
- It's resource intensive: building a version control system is not a small task.
- How do tags/topics get applied to code?
- Do the coders tag it (opening it up for voting to assess quality)?
- Does an automatic system tag (some of) it?
- Can the codebase be searched, and tags applied if the searcher finds something useful?
- Licensing: Is there a one-size-fits-all approach to licensing, or are licenses decided on a per-project basis? How does this affect plagiarism?
- Holy wars: Some people like Git, some like Mercurial, some like Subversion, some like ... and they all behave differently. What to choose?
So, over to you Stack Overflow community: thoughts?