31

From what I understood from the numerous discussions about Documentation and from the tour, Documentation is based on the following hypothesis:

documentation based on examples is more useful than a documentation based on specs.

Documentation tour identifies two problems of state of the art documentation

The problem I currently see with the Documentation is that it assumes that this hypothesis is true.

My proposal is: don't assume this; let the community prove or refute this hypothesis by upvoting the most useful pieces and downvoting the least useful ones.

If your initial hypothesis is true, we expect that the most voted pieces have prioritised examples. If there are no examples in the most voted documentation, then your hypothesis was refuted.

My hypothesis is that examples-based documentation is not a universal: some topics require explaining a concept through words, others an example is sufficient and advantageous. However, I assume that this may be wrong, because I haven't tested it.

IMO, the problem is that Documentation is currently presented in a way that it gives too much emphasis on writing examples, and it does not allow other possible hypothesis to be tested. More importantly, because you haven't presented any evidence that this is the best way to write documentation, only those that believe in this are willing to participate.

And guess what, there are lots of folks that are not convinced (me included) that this hypothesis is true.

Given the tools that Documentation has, I believe they would do a much better job to all of us by being a great tool to test the hypothesis, than being a tool that assumes it to be true. One of the best pieces of evidence of this is that lots of folks are extremely annoyed about the goal and focus of the Documentation. And believe me, we all want this project to succeed!

In summary, I suggest that we relax the example-focus of the Documentation, and allow more freedom for the community to use the tools to figure out what is the best way to write documentation. This could start by downgrading the It's all about examples. section of the tour.

If not, then present us undeniable evidence that documentation that prioritises examples is the most useful documentation.

If not, then don't expect folks to use their time on something that they don't believe in.

6
  • 17
    You should've just said "please un-ship Documentation". Documentation is examples. All the rest is fluff, and there's not much of it. Asking the powers that be to decrease emphasis on examples is sort of meaningless in my opinion: it would need a complete rehash of the system and the user interface (a rehash akin to many suggestions that have been made already, to no avail). Commented Aug 14, 2016 at 9:14
  • 7
    Documentation is only sort of examples/tutorials. When markE tried to contribute an example-focused tutorial on the use of HTML5 Canvas, it was deleted by a member of the Community team. The reason given for deletion appears to be it was "too much". Yeah. I don't know either. So, we want examples, but only short examples on simple, narrow topics. Or...something?
    – Cody Gray Mod
    Commented Aug 14, 2016 at 14:55
  • 9
    @CodyGray: I agree with the deletion. Given the current way Docs.SO works, it simply cannot handle that sort of tutorial. Tutorials of size and substance require order and organization, which the Docs.SO model is actively hostile to. He posted a 6 part tutorial that's intended to be read from Part 1 to 6. But they won't be read that way, nor can they be ordered that way. Docs.SO only functions well for relatively short examples on simple, narrow topics. Commented Aug 14, 2016 at 15:18
  • I thought about that too and maybe voting on topics would give some additional information. In a way we are already doing it when voting on the topic proposals. Commented Aug 15, 2016 at 9:52
  • Thanks for putting it in writing: meta.stackoverflow.com/questions/332268/…
    – JonH
    Commented Aug 15, 2016 at 18:41
  • 8
    I side with @AndrasDeak: My hypothesis is that examples-based documentation is not a universal: some topics require explaining a concept through words Yep, those already got books, tutorials, formal education, courses, and whatnot. This is exactly why we need a fluffless Documentation - without those topics. IMHO Documentation does not aim to be a complete reference of all what can be told. It aims to be more like a giant cheatsheet. That might be a better name for it, even.
    – ppeterka
    Commented Aug 15, 2016 at 19:53

2 Answers 2

15

Your post is based on two assumptions:

  1. Docs.SO is an experiment to discover what the best way to craft documentation. It's not.

  2. That competition would result in some objective winner.

Example-focused documentation is not popular, as evidenced by the fact that it is not widely available. That doesn't mean it's a bad idea, merely that it isn't popular.

So if you tell everyone to be as example-focused or unfocused as they want to be, then what will happen is that you'll get a lot of people who write non-example-focused documentation to participate. And thus, most of the documentation won't be example-focused. And therefore, you haven't really given example-focused documentation a chance to prove itself.

Oh sure, this means that domain experts like Michael Kay have decided not to participate in Docs.SO. But who cares about the contributions of people who are experts both within a field and within documenting that field?

Furthermore, since topics are so nebulous of a concept to begin with, competition within a topic is not an effective measurement of their quality. So even if you tried to use Docs.SO as an experiment, it wouldn't be a very good or decisive one.

5
  • 5
    I am not saying that it is an experiment. I am suggesting it to be one, or present evidence that the hypothesis holds. Because if it is not an experiment and there is no evidence that this model is better, why should anyone use their time to enrole in such a one? That is why I did the suggestion or asked for evidence. Some people are not convinced, but it seems SO team is, which bears the question: what evidence they have that we don't have? Because I would really be interested in knowing, so I can understand the rational behind "Documentation". Commented Aug 14, 2016 at 14:58
  • 12
    Not to minimize these problems with Documentation, but I don't really think these are Michael Kay's problems. He seems to have been confused and frustrated by the user interface, rather than the unclear focus. He didn't get far enough to be frustrated by that.
    – Cody Gray Mod
    Commented Aug 14, 2016 at 14:58
  • 11
    @J.C.Leitão: "why should anyone use their time to enrole in such a one?" What, the massive and unending tide of low-effort rep isn't a reason ;) Joking aside, they want to attract people who want to write example-focused documentation. That is, they want to convince people by example, thus proving their point, by building good documentation based on examples. Granted, the fact that Docs.SO is complete garbage from both a quality and organization standpoint and is not getting any better is kind of a disproof by example... Commented Aug 14, 2016 at 15:14
  • "is not popular" - to produce or to consume? Commented Aug 16, 2016 at 14:26
  • 2
    @jinglesthula: Clearly, it's not popular to produce. And since it's not popular to produce, it's hard to analyze how popular it is to consume. Commented Aug 16, 2016 at 14:29
3

The wisdom of crowds does not always produce the optimal solution.

It may well be that the Docs team did their best and came up with something sub-optimal. Whether or not it needs to be fixed, I don't know. I think it would be good to take examples of what the community considers to be very high quality, useful documentation, as well as examples of poor documentation and find common threads. Then design a collaboration tool that enables (and incentivises) the creation of docs that adhere to the good and avoid the bad.

Personally, I think examples-focused docs seems like it adheres to what Kathy Sierra described in her excellent Fluent conference keynote on learning as a developer: http://conferences.oreilly.com/fluent/javascript-html-2015/public/schedule/detail/40366

Whether this is a good implementation of the idea of perceptual learning is something worth exploring. As is the question of whether the purpose of documentation (or Documentation) is to teach, to be a quality reference, or to be something else.

Not the answer you're looking for? Browse other questions tagged .