2

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

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

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 . You open a file in a project and find that , and 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?
  • Code Licensing: Is there a one-size-fits-all approach to licensing the code added to the system, 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?

5
  • Related: Rename “Documentation” to “Examples” Commented Apr 18, 2017 at 14:36
  • 1
    meta.stackoverflow.com/questions/328592/…
    – davidism
    Commented Apr 18, 2017 at 16:06
  • Sure, why not? At least you have a coherent vision of what you want. Commented Apr 18, 2017 at 19:11
  • An alternative is to have a collection of examples of code [...] each tagged with a number of topics Sounds an awful lot like what we have right now on Stack Overflow. You can filter question by tag(s) to find a "topic" and then use search terms to narrow it down from there, or just sort by votes and see the biggest contributors. Commented Apr 20, 2017 at 12:12
  • @NathanOliver Not necessarily a coincidence ;) I see the main difference as the idea that "Documentation" should be based on real-world example code, and where better to get that than real-world projects? The examples on the Q&A are still very often contrived and limited to a single topic (as they should be!), and usually fitted around the asker's existing code rather than best practice.
    – Philip C
    Commented Apr 20, 2017 at 12:30

0

Browse other questions tagged .