16

I was under the impression that Documentation was geared towards self-contained, short and pragmatic examples, since often we learn something by first trying it.

However, prose seems to prevail and people start piling edits over edits, transforming what was quick to read into endless descriptions!

It seems that everyone wants to add their 2 cents, but what I thought would be a very simple and basic example becomes a monster overnight!

How do we convey/enforce the message that we want examples to be: try first, read about it later!?

Otherwise, I do not see how this is going to be better than searching Stack Overflow.

EDIT

I think my message is getting misinterpreted. I personally prefer concise explanations over a sentence that dishes out all of the details. Often these details are not relevant in every situation, so why not let another example explain the particular case?

I will give you an example in Matlab about the transpose operators. Tell me, would you like the big chunk of text before or after the examples? Also, is the paragraph concise and mostly relevant?

EDIT

It seems that quantity will dominate unless there is a change in the approach: Minimum tag score for adding documentation. The post raises a more generic concern and my question is just a specific manifestation of that problem.

9
  • Also, this post is related since I operate in the Matlab language.
    – Oleg
    Commented Jul 22, 2016 at 10:39
  • 1
    I've been scanning through Java topics and what I see seems really good. Short descriptions with to the point examples. Perhaps it is a topic-specific problem? Can you give an example of a documentation page that you think is really bad?
    – Gimby
    Commented Jul 22, 2016 at 10:56
  • 3
    I hope there's something I'm missing about the Documentation and that the bigger picture reveal itself later, but I agree that currently it's a weird mix of random topics with random examples and mini tutorials - Too fragmented
    – Alon Eitan
    Commented Jul 22, 2016 at 11:51
  • 3
    Small, isolated examples have limited value in some contexts. In my opinion. A lot of people can't figure out how to layout webpages with CSS because they learn about each property in isolation.
    – HK1
    Commented Jul 23, 2016 at 2:49
  • 6
    "How do we convey/enforce the message that we want examples to be: try first, read about it later!?" I think first you have to convince people that "try first, read about it later" is an effective means of conveying information, rather than just feeding the needs of copy&paste coding styles. Commented Jul 24, 2016 at 23:31
  • I read code much faster than prose explaining it. I prefer visualizing a concept than reading it. So, maybe it's my personal preference, and if that's the case, then I doubt that a collective effort with no clear guidelines will outpace any centralized effort with a standard approach. Again, maybe personal experience, but first I look at syntax, then i jump straight to an example. If something is not clear, I go back and read about it.
    – Oleg
    Commented Jul 25, 2016 at 0:33
  • @NicolBolas You might be assuming a certain quality of the prose...
    – Oleg
    Commented Jul 25, 2016 at 0:51
  • 1
    @Oleg: "You might be assuming a certain quality of the prose..." Yes. Just like the quality of code is relevant to whether or not code can effectively communicate. Commented Jul 25, 2016 at 2:17
  • Thank you for the example you added. See, I don't see a "big chunk of text" there. I see a description that can be read in a very short period of time. Not too short, not too long - just right. Discussions like this get difficult when there is no universal measure of "too long".
    – Gimby
    Commented Jul 27, 2016 at 13:11

2 Answers 2

18

To most programmers, documentation means either a tutorial (e.g., most books) or a reference manual (e.g., Javadoc, man pages), not a collection of short examples. I'd call the latter a cookbook. Unfortunately, SO decided to name the feature Documentation and then try to tell people it's meant to be a cookbook, resulting in much confusion and disappointment when expectations aren't met.

So, my proposal is to rename the feature to the Stack Overflow Cookbook.

I know this isn't likely. SO is committed to the Documentation brand now, and maybe the company still thinks it's an appropriate name. And as a certain other SE site knows, renaming is a slow and contentious process. But I think the best way to communicate what Docs is supposed to be is to give it an appropriate name.

As a bonus, Cooking.SE will eventually get the Seasoned Advice Cookbook.

5
  • 3
    It is exactly because of this confusion that I sought for some clarification. The SO team might also be collecting feedback in order to decide what's the best next step.
    – Oleg
    Commented Jul 25, 2016 at 0:35
  • 2
    The next step is to abandon this foolishness and apologize.
    – chx
    Commented Jul 25, 2016 at 9:59
  • @chx At this point we've come too far. It's true that there are huge issues, but the developers are working on solving them. Don't lose hope yet, we're just waiting for the updates to roll out. Commented Jul 25, 2016 at 17:08
  • 4
    @4castle: That assumes you believe that what they're working on solving are the actual problems, rather than the problems that they believe exist. Because quite frankly, 80% of Docs.SO's problems were forseeable, and many were brought up and dismissed throughout the private beta. Why should we trust that they've seen the light now? Commented Jul 25, 2016 at 17:11
  • Back when the naming of this new aspect of SO was being discussed, I and others also suggested incorporating the concept of a "cookbook" into the name. And doing so arguably would have made its purpose much more focused.
    – DavidRR
    Commented Jul 27, 2016 at 15:16
16
  • The primary focus of Documentation is clear and concise examples.
  • Examples should illustrate solutions to common problems and ways to accomplish common tasks
    • Examples should be broader than the typical answer. Q&A still exists, after all.
  • Syntax, Parameters, and Remarks support Examples
    • they should reduce duplicate explanations
    • they're optional because there isn't always duplication to reduce

We're four days into public beta, so I'm not all that surprised we're not seeing perfect focus from contributors. In particular we've got a problem with too many examples (being too exhaustive), and overly long examples. We're working on changes to address these, amongst other issues.

3
  • 12
    Examples of good Examples would be really helpful. I mean, I can imagine what you probably mean by "concise examples...[that]...should be broad...", but those adjectives aren't exactly naturally complementary.
    – jscs
    Commented Jul 25, 2016 at 17:43
  • 8
    Does cookbook capture what you're looking for? That's something many people will recognize, as opposed to documentation which many people interpret differently. Commented Jul 25, 2016 at 17:49
  • 6
    "Examples should illustrate solutions to common problems and ways to accomplish common tasks" ... so why are examples collected into "topics" instead of "tasks"? That would solve a number of the problems with Docs.SO. Commented Jul 26, 2016 at 22:31

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