35
votes
Do we need to adapt our voting system for documentation examples?
It's not voting system that needs to be changed, it's sorting that is inadequate.
There're all sorts of websites with this exact problem: people vote for things others have voted for. Sorting by ...
34
votes
Documentation: Codeless topic - still having real value. Should it stay, or should it go?
Installing the platform seems like a reasonable topic. But...
...The examples should actually demonstrate how to install Java. Right now, this is just a grabbag of information that... Is relevant to ...
34
votes
Reducing the number of examples in huge topics to currently recommended 6 (12) examples per topic
The number of examples in the largest Python documentation topic Compatibility between Python 2 and 3 was a symptom of far worse problems with the documentation system.
The current state of that ...
22
votes
Why does my improvement request bar me from handling anyone else's?
I made the request so obviously I can't handle that part
... why not? As far as I'm concerned, an improvement request is just a todo list. And there's no reason why you can't decide later to take the ...
21
votes
Are examples allowed to be too large?
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 ...
17
votes
Accepted
Should counter examples be included in Documentation?
I think the counter example should be included within your right example. So the user know that the counter example go with this example and not another one.
If, with time, a lot of examples are ...
15
votes
Accepted
Are multi-step examples wanted, in the documentation?
No, examples should be self-contained and should not depend on the order or content of other examples because:
The order is not guaranteed
The content of the other examples can (and will!) change
...
10
votes
Documentation examples are not examples
Looking at the OP's example, these are my thoughts.
TL;DR: Don't hesitate to make good edits, even though the rep and vote feedback systems are bad. Split Examples up as new Topics where appropriate....
7
votes
Accepted
The Dreaded Java Arrays "topic" - rate my draft
I don't see the Java Array's example being fixed unless one of two things happen:
authorship can be split
deletion
It needs to have its authorship split so that the content can be split. At present, ...
7
votes
Are examples allowed to be too large?
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 ...
7
votes
Accepted
Calculation of major/minor contributions is broken
This has been fixed in the latest deploy.
The root cause was that there were a couple ways* an edit could get counted multiple times. For example, user3185569's edit was getting counted 3 times; and ...
7
votes
Documentation: Codeless topic - still having real value. Should it stay, or should it go?
My opinion is that documentation about a language, like Java, should only show off language features, syntax, available API methods, and basic usage.
Showing someone how they can become a Java ...
7
votes
Accepted
Are obsolete documentation topics allowed?
I think it's referring to a different type of obsolete Documentation. The other two terms clearly refer to organizational changes.
That leads me to believe that it refers to any situation where the ...
6
votes
Notification of my examples being deleted
This really sounds like a good idea if ownership is applied to individual examples, which can typically be done for most small and/or new examples, but it would really just be an irritation with ...
6
votes
Accepted
Documentation - how to suggest "eliminate an item"?
There already is a delete link. It's right here (you need to be in edit mode):
5
votes
Maximum number of examples (6) exceeded?
There are only three levels of hierarchy in Documentation right now:
Tags are pretty straightforward; they correspond roughly to tags in Q&A (although not all Q&A tags make for good ...
4
votes
How to improve documentation (and copy pasting official docs)
If this would be a question I would leave a comment, but this isn't possible in the Documentation pages. So what is the best way to deal with this?
If you don't have time to actually add that ...
4
votes
Accepted
How to handle duplicate example exist on other website (Which is not plagiarized)
The content was originally written by the user, but for another website
So long as the author didn't give up ownership to some other entity and still retain it, that's not a problem at all.
I don'...
3
votes
Accepted
My Example got approved, but never got the reputation for it?
When I go to your reputation tab, I see this:
The +2 comes from the approved change to the topic and the +5 comes from an upvote to the example. So I can't reproduce the problem.
3
votes
Are examples allowed to be too large?
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 ...
3
votes
Accepted
Documentation Example - Improve instead of delete?
I found where you proposed the change: Page 3, Here. An easy way to find all this would be from your profile.
The example was originally reverted here.
According to the edit summary, it was deleted ...
3
votes
Should documentation examples' highest vote be the most generic example? If it's voted too much what should I do?
Generally... I don't agree with your thesis that Docs should cover best-case-scenario problems rather than those people struggle with in reality. To uncover the latter, we rely on votes and requests ...
2
votes
Accepted
Additional points for citing an example?
The help center describes the reputation gain:
first time an answer that cites documentation you contributed to is upvoted: +5
These descriptions by their terseness leave out a few ...
2
votes
Accepted
Viewing revisions of a moved example created prior to the move results in 404 page
This should be fixed in the next build, thanks; specifically, the link between steps 5 and 6 will link to the correct topic for the chosen revision.
2
votes
Are examples allowed to be too large?
The best example code I have read are small, easily understood examples that are large enough to demonstrate only one issue or interaction.
2
votes
Accepted
Documentation Example modified by other user and now deleted
To revert this change, first click the revision history at the bottom of the page:
Then, find your edit and click “View Topic.”
Next, click on “Create draft rolling back to this version:”
Click “...
2
votes
Accepted
Documentation contributor chain on an Example is broken after a Topic move
Nice large stack of issues here, made it harder to figure out exactly what went wrong with this badge award.
First, a bug: the Creditor badge wasn't properly checking that the cited Documentation ...
2
votes
Accepted
Option to merge two examples (or delete one) in documentation
You already can delete examples. Just click the trash can icon at the top-right in edit mode.
You already can merge examples. Delete one and copy/paste its contents into the other.
1
vote
Accepted
Shortened links to topics and examples in Documentation
There are slightly longer versions than the ones you propose in place already:
http://stackoverflow.com/documentation/s/t/<topic-id>
http://stackoverflow.com/documentation/s/e/<example-id>...
1
vote
How to deal with intersecting documentation topics?
XML is too vague of a tag to be useful in documenting something like library specific examples.
In this case, document the serialization examples in the serde tag.
I believe the best approach to ...
Only top scored, non community-wiki answers of a minimum length are eligible
Related Tags
documentation-examples × 47documentation × 43
discussion × 21
support × 9
bug × 9
documentation-topics × 9
feature-request × 8
status-completed × 4
deleted-examples × 2
edits × 1
design × 1
reputation × 1
voting × 1
stack-snippets × 1
upvotes × 1
hyperlinks × 1
status-norepro × 1
revision-history × 1
documentation-proposals × 1
character-limit × 1
docs-contributors × 1