21

There is some debate on what the size of an example should be. Some of the discourse has been focused on the balance between prose and code, and some between snippet or tutorial.

However, I would like to address character limits of examples. At the time of writing, the semi-famous Java Arrays example sits at 16,049 characters and currently (as well as previously) has several improvement requests stating that it is too large.

That said, this is not about that specific example, but about the size of examples in general. The (assumed) character limit of examples is the same as answers which is 30,000.

If an example which is half that size (ish) is as problematic as it is made out to be (debatable), then should the character limit for examples be altered to reflect the mindset that examples should not reach the 30,000 character limit?

19
  • 25
    (grumbling) Honestly, that Java arrays topic is the greatest example of bikeshedding...
    – Makoto
    Commented Aug 18, 2016 at 23:30
  • 3
    Yep, let's color the bikeshed in red! Anyway, yes, it's far too large … a limit of 10k chars per example would be enough, but is this really important? Too large examples shall just be split up and fine; the size limit is rather meant as a protection to not spam 1 MB of garbage, not as a real limit on the content, I think.
    – bwoebi
    Commented Aug 18, 2016 at 23:37
  • 1
    @Makoto - Yeah, it needs many things. For example, a way to break apart ownership to users who contributed useful parts if the example is placed into several examples across several topics. If one user does it, then they essentially become the owner as a result of creating a new example and pasting into it because the example can only be moved to one place to retain all the authors. That is essentially the aftermath of having this large character limit though, and I was hoping to get a discussion on whether or not that limit should be changed, and what those changes could look like.
    – Travis J
    Commented Aug 18, 2016 at 23:37
  • 2
    @bwoebi - "we've looked at posts at or near the 30k limit and with rare exceptions, they are .. problematic. So length has a strongly inverse correlation with quality" -Jeff Atwood
    – Travis J
    Commented Aug 18, 2016 at 23:46
  • 1
    Bikeshedding or not, Documentation tries to be a general reference to other programmers and should therefore be as broad as possible. Therefore, posts should probably be as long as needed. As this is also a community process where everyone can and should contribute to, if one finds a shorter explanation or understandable example for the topic s/he is free to edit the post. In the case of the Arrays example, maybe someone can split the subsections into own posts or compress the information further to reduce the length. Commented Aug 19, 2016 at 0:01
  • 7
    @RomanVottner: The problem right now is that there's no good way to split an example without claiming the credit for the examples you move. From an attribution and reputation standpoint, people are (rightfully) reluctant to split large posts even if it's clear they should. This is a problem we'll need to fix so that we can avoid getting anywhere close to the 30k limit. (As an aside, we are really looking at narrow examples that can be found via search.)
    – Jon Ericson Staff
    Commented Aug 19, 2016 at 0:12
  • 2
    @JonEricson: "The problem right now is that there's no good way to split an example without claiming the credit for the examples you move." There's an easy way to stop that problem: take away "attribution and reputation". Commented Aug 19, 2016 at 0:20
  • @NicolBolas: I guess we'd need to throw out CC BY-SA too, in that case.
    – Jon Ericson Staff
    Commented Aug 19, 2016 at 0:23
  • 2
    @JonEricson: Personally, I've got no problem with the idea that, if you put something on Docs.SO, you're assigning copyright for it over to SE. Commented Aug 19, 2016 at 1:27
  • 12
    It seems like you already have, @Jon. I mean, there is nothing on the page with the example that contains my user name. That right there seems like a massive violation of CC BY-SA, specifically the part about attribution. You have to go to a separate page, the "edit history", in order to see the user names of the contributors. The tiny avatar icon is not sufficient. If a 3rd party scraper did that for SO Q&A, you'd be sending them a friendly reminder email. Not that I'm complaining—given Docs' obsessive focus on collaborative editing, CC BY-SA arguably does not make sense as a license.
    – Cody Gray Mod
    Commented Aug 19, 2016 at 9:22
  • 4
    @CodyGray Hasn't Wikipedia the same problem? They use CC-BY-SA for the content and still famous pages can easily have hundreds or thousands of authors. They don't show the names on the page, they are only available in the history. I assumed the same idea would work here too. I just wonder how to attribute properly if using parts of Docs (or Wikipedia for that matter). Do I have to mention all (possibly hundreds or thousands) of authors of the part I use? I think they modified the BY part somewhat, effectively arriving at CC-SA with a link to the relevant SO page for all practical purposes. Commented Aug 19, 2016 at 10:09
  • 1
    @CodyGray Actually it doesn't seem to be modified. On the Attribution Required they still mention "Show the author names for every question and answer" - so I guess one would have to write down a very long list if wanting to properly use parts of Q&A or Docs. Of course nobody is going to do that. Commented Aug 19, 2016 at 10:15
  • 1
    The other problem right now is that we have a limit on number of examples, so we can't split up big examples (in the same topic) because we can't add more, smaller examples. This is an argument for more, smaller topics, but it's hard enough (in some smaller tags) to get simple moves approved (I've got a proposed change from 11 days ago still pending in DOM). Commented Aug 19, 2016 at 13:56
  • 5
    That topic title is a little problematic... "too large" would inherently imply that no, they are not allowed.
    – TylerH
    Commented Aug 19, 2016 at 15:06
  • 4
    @JonEricson: "(As an aside, we are really looking at narrow examples that can be found via search.)" --- At the risk of continuing a tangent... that's exactly the opposite of what the Documentation tour says they want. Examples (emphases mine): "What's different from Q&A? Documentation is broad [...] You aren't documenting a specific problem", "Good examples are broad and generally useful, remember that Q&A exists for very specific questions!", and "Don't be too narrow". Commented Aug 21, 2016 at 5:30

4 Answers 4

21

I think you're trying to conflate the limits imposed on answers/examples with the reasonable limits for making a useful example. Of course, that's based on the question of what a good example looks like.

The Creating and Initializing Arrays example is not an example; it's a section in a Java book. It tries to cover everything about creating/initializing arrays. It covers multidimensional arrays.

Because it's essentially a section out of a book, that makes it hard to actually find information you're looking for. If you're interested in knowing how to deal with multidimensional arrays, you have to sift through a bunch of single-dimensional array stuff to get there.

The example is also very unfocused. It covers Java language arrays, Java collection types like List<T>, and even streams. It even ends on some information about sorted arrays.

Because if you're looking for information on streams and sorted arrays, the best place to look is in an example called "Creating and Initializing Arrays".

This goes back to the same "What is a topic" problem. Why? Because you don't get these gigantic and unfocused examples in in well-focused topics. Just like you usually only get 30,000-character treatises in overly-broad questions.

Bad examples come from bad topics. Make focused topics, and you get smaller, bite-sized examples.

6
  • 16
    "it's a section in a Java book" at which point you have to really, really wonder how documentation was sold at the start, and what it was left to become.
    – Braiam
    Commented Aug 19, 2016 at 1:17
  • Even from a focused topic, in your opinion is a 30,000 character example excessive?
    – Travis J
    Commented Aug 19, 2016 at 6:28
  • 1
    @Gimby - I was referring to characters, and in my opinion the use of "words" was probably a typo in the answer.
    – Travis J
    Commented Aug 19, 2016 at 10:11
  • @TravisJ you were right, it was a typo :)
    – Gimby
    Commented Aug 19, 2016 at 15:19
  • Is something like java and rule-engine also considered to be a gigantic and unfocused topic? Imagine someone would post something like this basic rule-engine implementation, which also has roughly 17.000 characters, do you also consider this post as to unfocused or to long? Sure there might be many ways to do it, but shouldn't the code also have some documentation and explanations why something was done like it was done? Otherwise a gist-like system would probably preferable IMO Commented Aug 19, 2016 at 16:45
  • 4
    @RomanVottner: The question you linked to is basically, "How do I write a simple scripting language?" It's extremely broad for an SO question. And yes, it's still too broad for a Docs.SO topic. "Java" and "rule-engine" are not topics; they're tags. Commented Aug 19, 2016 at 16:49
7

We are faced with the classic "balloon squeezing" dilemma.

If you squeeze on one part of a balloon, the other part of the balloon will expand


If you limit the quantity of Examples in a Topic to 7~13 then one of 3 things must happen:

  • The size of Examples will expand.
  • The quantity of Topics will expand.
  • The content will shrink to fit in the available space allowed.

The size of Examples will expand

There is nothing inherently "bad" about long examples, but the Powers-that-Be like Jon Ericson indicate shorter, pithier and narrowly focused examples are desired. He says "...we are really looking at narrow examples..".

The P.T.B. are saying "Keep examples small".

An aside: If a long example is required, newspapers are a good example of long-form writing. Newspaper articles place the most important points at the top of the article with decreasing importance as the article progresses. This way the reader can consume up to the point they get what they need.

The quantity of Topics will expand

A long subject can often be divided into multiple, smaller, tightly focused Topics.

This is advocated by Nichol Bolas who is either a Power-That-Be or one of the Loyal-Opposition (I can't figure out which).

Momentum is quickly carrying Docs away from larger quantity of focused Topics

Documents are not currently organizing themselves into multiple, focused Topics. Instead, currently, Topics have broad titles with (I assume) broad examples to match. At some point in time, momentum will carry Document organization past the point of being restructured into more, multiple & tightly focused Topics.

The content will shrink to fit in the available space allowed.

If constrained in all directions, content will be made more concise -- or will not be written at all.

If... the PTB are limiting the size of examples (either by suggestion or by edict),

and if... momentum is prohibiting DOCS from having more-but-focused Topics,

then... some content will be short & concise and other content will simply not be written because there is no available space for that content.

4
  • Very nice answer. Just curious: What would you prefer to do? Squeeze the balloon and if so where? Commented Aug 19, 2016 at 19:30
  • 2
    Well, I must favor concise examples because the PTB are insisting on shorter examples. After a long comment-chat with Nichol Bolas I'm trying to adopt his philosophy of more-but-focused Topics to allow adequate space for concise examples. But the tide is definitely against focused Topics. There are a lot of one-word Topic titles which invites a broad range of examples. I have no influence with PTB, but I would add at least one more organizational layer to Documents...maybe "tag, CATEGORY, topic & example.
    – markE
    Commented Aug 19, 2016 at 19:52
  • 7
    "This is advocated by Nichol Bolas who is either a Power-That-Be" If I were a "Power-That-Be", then believe me, Docs.SO would look a lot different. Commented Aug 20, 2016 at 5:37
  • @NicolBolas. Chuckle!
    – markE
    Commented Aug 20, 2016 at 5:42
3

Large examples do not have to be bad per se (even if many of them are). For some topics good examples might need to be longer than for other topics. That's the reason why a hard character limit always must be rather generous and will almost never be helpful in defining the quality of an example alone!

Or what are we supposed to do with a 16,049 characters long example? Shorten variable names? Splitting it up? If so how? Removing spaces?

30,000 characters is (with say on average 40 chars per line) 750 lines. This is indeed very generous, but can we really rule out there won't be good examples of this size? A complex algorithm maybe that needs lots of explanation?

On the other hand we can readily take the length as a strong hint that the quality might (!) be low. We could regularly inspect all long examples (make an interface for sorting examples by length for each tag) and discuss how they can be improved. Maybe along the way we can define criteria for what a good example is - my guess is that length is only one factor among many.

Regarding the semi-famous Java Arrays example. Just split it up. It can easily be splitted up in smaller topics, however this doesn't reduce the total amount of information in that topic, does it? The goal should rather be to reduce redundancy and split/combine examples so that the overlap is minimized and the usefulness maximized.

As for attribution, when splitting or combining content, the history should be preserved Git-like, so it's clear who contributed to each line.

6
  • 3
    Nice answer, but "A complicated algorithm" - the fact that you have to call it complicated makes it shaky territory for Stack Docs in my current understanding of its focus. The whole point is to be able to get up and running quickly by having code examples rather than explanatory text. That means not all engineering-based algorithms in the world have a place on it, schools and textbooks still have a purpose ;)
    – Gimby
    Commented Aug 19, 2016 at 9:14
  • @Gimby You're right. We can surely discuss which topics can be covered here and which not. I exchanged complicated by complex to indicate more that examples could consist of many steps, even if they are not terribly difficult to understand. To give an example for an example of an algorithm that would probably require a bit longer to explain but might be interesting for Docs: BLAST requires about 12 steps that would need to be explained. (Wikipedia manages it with about 10k characters but without any code) Commented Aug 19, 2016 at 9:54
  • @Gimby Maybe the question is also about the level of detail in an example. For example there could be "high level examples" that explain you a general strategy without much going into detail but lots of references to other examples/ other content giving the details. They could be kept short. Commented Aug 19, 2016 at 9:56
  • 1
    Well it would be an interesting discussion to see if something like the BLAST algorithm is on-topic on Stack Docs. You'd get examples on implementing that algorithm in umpteen languages. And then where is the limit on what algorithms are allowed in on the site? The floodgates would open.
    – Gimby
    Commented Aug 19, 2016 at 11:00
  • 2
    @Gimby I fully agree. That would be very interesting. Just as a small comment here: Algorithms are ontopic on Q&A, there is even a tag about BLAST with 140 questions. Surely some of them would be ontopic for Documentation too. But where to stop? How much detail to put? What to leave to other specialized sites? In a way, the creators of Documentation wanted to open the floodgates wide, but where does it become impractical? Commented Aug 19, 2016 at 11:06
  • 3
    @Trilarion when nobody uses it because 1) they can't find anything 2) the people that can make things findable feel disheartened.
    – Braiam
    Commented Aug 19, 2016 at 14:42
2

The best example code I have read are small, easily understood examples that are large enough to demonstrate only one issue or interaction.

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