74

I was thinking about the order of the documentation page. For example when I open Java Documentation it should show the first topic as Introduction then Hello World Program and so on. Why is it not there? It would be better if there were an order.

9
  • 2
    Kind of like my question: meta.stackoverflow.com/questions/331804/… Commented Aug 8, 2016 at 17:11
  • 2
    And kind of like my feature request: meta.stackoverflow.com/questions/329743/…
    – Tot Zam
    Commented Aug 8, 2016 at 18:18
  • 4
    And mine: More hierarchical structure needed for documentation topics
    – Suragch
    Commented Aug 8, 2016 at 21:06
  • 30
    This is pretty much why I gave up on documentation. A shotgun approach to examples is more what it is than "documentation."
    – enderland
    Commented Aug 8, 2016 at 21:16
  • And a 'custom order' feature request during beta
    – Myrtle
    Commented Aug 10, 2016 at 8:58
  • stackoverflow.com/documentation Commented Aug 10, 2016 at 16:56
  • Does it need to be ordered? Maybe topics are intended to be accessed via search. Commented Aug 11, 2016 at 1:50
  • 5
    The need for an ordering (or indeed any other presentational aspect) of any document or documentation depends heavily on the intended audience/use-case. Alas, a statement of the intended audience/use-case for SO Docs seems to be absent. Commented Aug 11, 2016 at 11:33
  • I agree with @OliverCharlesworth above. I doubt the docs will ever be intended as a coherent "tutorial" of for instance Java. I see it more as a reference for people to refer to from Q/A and as entry points from search results. There was a site a while back called example depot (seems to be mirrored here now) which I often found really useful. And I never missed the functionality of being able to read the examples in a tutorial like way.
    – aioobe
    Commented Aug 11, 2016 at 13:56

7 Answers 7

32

There is no mechanism to order documentation currently.

However I greatly believe there should be, the C++ vector is a perfect example of why! Compare the C++ reference website to the Current C++ Vector Documentation.

There are so many details and caveats to using something complex like a std::vector that the page is quickly becoming a nightmarish info-dump.
There needs to be some mechanism whereby the std::vector page is a topic heading/title page, from which sub-sections can be reached with ease.

7
  • 2
    It seems to me there could be a single introductory post pinned to the top of each section which could be used to describe how all of its parts fit together. Links to detailed instructions could be added for completeness. Commented Aug 8, 2016 at 18:28
  • 37
    I've been very tempted to resort to the hack Adam describes: writing a "table-of-contents" example and pinning it to the top. I'm not sure how the community feels about that. It is clearly a violation of how Docs is supposed to work, but as you point out, it simply is not working for most things in the C++ tag. (Personally, I think that's because they only considered writing documentation for extremely simple APIs where one or two examples explain everything when they were designing this business, and some of the team's comments jive pretty well with that theory, but we have what we have.)
    – Cody Gray Mod
    Commented Aug 8, 2016 at 19:06
  • 1
    @CodyGray I don't know about the community, however I have to agree the temptation is pretty-damn big. The way documentation is supposed to work, and how it needs to work, are currently VERY different. This system works well for HTML and base-Javascript. It falls down with complex languages with a million caveats (such a C++, Java, etc) Commented Aug 8, 2016 at 19:12
  • 1
    @CodyGray I agree that pinning a "table-of-contents" at the top would be useful and a very simple solution. I tried creating something similar in the first week of documentation but it got rejected by mods (it was to organized topics instead of example though).
    – Gudradain
    Commented Aug 8, 2016 at 19:29
  • 1
    @CodyGray I have a hard time understanding what other purpose "pinning" could even serve. I couldn't find much discussion on its accepted use (basically just meta.stackoverflow.com/questions/330456/…). It seems to me like it is currently being used mostly to impose a tiny bit of order on docs, ensuring readers see the "Hello World" example first. Might as well expand that so that the intro example also notes and links to further reading - meaning it's still a full example (not just a table of contents) but serves the indexing purpose
    – Mikegrann
    Commented Aug 8, 2016 at 19:35
  • 8
    This std::vector reference page is far better than the one linked above and even further highlights the problems with the documentation on here. Commented Aug 9, 2016 at 0:19
  • 1
    I've been saying this for weeks. +1
    – Marco A.
    Commented Aug 10, 2016 at 17:44
19

I agree that it would be better if there were an order.

There is currently no ordering by design:

We don’t really think, based on observation and personal experiences, that there’s a ton of value to be had in strict hierarchies. They also add big points of contention and debate, plus some serious technical issues (like, what happens to Topics when the hierarchy is modified, who can modify it, how do you modify it?). The tradeoffs don’t make much sense, in other words.

However, I would like to emphasize again the benefits that logical ordering would bring:

  • Provide an alternate search route when Google fails.
  • Make sure that topics are not too broad and that examples are collected in the appropriate place.
  • Give learners a logical path to follow from topic to topic.
  • Prevent topic duplication and reduce the need for merging.
  • If a topic does not exist (i.e. there is no content for a particular item), then it is a centralized place to make a topic request. Random, unorganized requests are reduced.

This is still the beta and the developers are seeing how Documentation is being used. I hope they will bring us something more of the structure that is already used by almost every other documentation out there. If they go that direction, I believe the technical issues can be overcome.

5
  • 4
    Not sure if Documentation is used much currently. I look at the topics list and if I don't see an interesting topic on the first two pages I give up. Google so far, mostly brought me to Q&A on SO. Commented Aug 9, 2016 at 6:57
  • 3
    Of course a logical ordering would benefit docs greatly. However, getting 2 people to agree on what that ordering should be and why it is the logical order is very hard. Say you go with Beginner, Intermediate, Expert. What would changing a string to upper case fall into? Turns out it is really hard while beginners think it is easy. So if you don't know the topic you don't know where it would be categorized in. Forcing one objective ordering for all topics has lots of issues. Allowing inconsistent orderings across topics does too. I can see why they want to stay clear of that.
    – nwp
    Commented Aug 10, 2016 at 8:39
  • 1
    The official docs generally order the API by parent and child classes. It seems like we could do something similar. A skeleton hierarchy could be provided as a framework. For non API topics I can see how there could be disagreement, but it seems that most any sort of topical ordering would be better than sorting by vote count. @nwp
    – Suragch
    Commented Aug 10, 2016 at 14:36
  • 5
    @Suragch That really only works for languages like Java. C for example doesn't have inheritance, C++ does but most classes don't inherit anything. The whole functional programming community just gets screwed. One could add a list of topics that are prerequisites and build the hierarchy from there, but if an example requires detailed knowledge of another topic it is probably not a good self-contained example.
    – nwp
    Commented Aug 10, 2016 at 14:59
  • 2
    @nwp, What about a hierarchy loosely based on the official docs for each language? My main complaint with the official docs is that they don't have good (or enough) examples of how to do things.
    – Suragch
    Commented Aug 10, 2016 at 15:15
5

As it currently exists there isn't really a way to order the topics/examples. How would it even be possible? Should an explanation on objects come before or after an explanation of loops and selection statements in x language?

Documentation isn't about learning how to program from scratch its meant as a resource for someone who knows what they are looking for (and who will use the search bar).

6
  • 12
    Disagree here. There is a logical (or perhaps arbitrary) ordering to e.g. the Python docs or the Ruby docs. If this is the way it's meant to be, the sorting might as well just be random.
    – hichris123
    Commented Aug 8, 2016 at 15:02
  • 8
    @hichris123: That's clearly not how Stack Overflow has designed their flavor of Documentation.
    – BoltClock Mod
    Commented Aug 8, 2016 at 15:08
  • 6
    Apparently not, @BoltClock, but who's to say that's the correct way? At least from my (small) experience with Docs, sorting by votes is rather confusing.
    – hichris123
    Commented Aug 8, 2016 at 15:11
  • 42
    @hichris123: Everyone is confused.
    – BoltClock Mod
    Commented Aug 8, 2016 at 15:14
  • 2
    Hmm... as an aside, in the case you mentioned, I would suggest ordering it as variables > loops & conditionals > objects. Commented Aug 8, 2016 at 17:02
  • 2
    The order could fall on a Doc admin, for that specific category. A user perhaps that is considered an "expert" in that specific catagory or an actual SO admin.
    – Bean0341
    Commented Aug 8, 2016 at 20:20
4

I think the best way to order things would be a tree diagram -- there is a basic "trunk", with intro stuff, and after that it branches out into branches, stems, leaves, etc. Some opposition to the idea of ordering stems from (pun!) the idea that some things are not necessarily more complex or should be learned after another -- let's take primitives and strings for example, (although I think there could be a case for primitives before strings). A tree diagram would allow some things to stand equal to another on footing. See below:

enter image description here

This is a very rudimentary and incomplete framework, but you can see the idea. The "trunk" branches into primitives & strings, which both point to arrays, and so on; the second branch starts with inheritance, then continues into polymorphism, and that branch could very well continue with annotations (for @Override) or whatnot. The complete one would have many more branches extending from the trunk. Keep in mind the idea is not that "inheritance" is a "group" of subjects and everything under it is a part of that group -- instead, its supposed to display multiple paths of learning that cannot be reconciled or fit together in one, neat ordered column. The idea is not perfect, and no idea or solution to this can be, but I think it gets the job done and would be helpful for everyone ranging from beginners to professionals seeking a particular learning "path" or "stream" for a language of subject.

2

Of what I've seen notable examples are pinned to top. On the more popular documentation pages (C#, Java..) the amount of topics can reach approx 150, that's about 8 pages.

Currently the orders are by popularity and last active, that doesn't help very much if I'm looking for some small niche topic that I know begins with a certain letter.

I think there should at least be a sort by letter or pagination by letters or something of the sort.

Another approach would be input boxs that will search/filter out topic and examples.

1
  • I agree to that point. There should be an order.
    – PSN
    Commented Aug 10, 2016 at 15:26
0

I think we can have a extensive proposal stage for documentation. The last time I checked, I just needed one upvoted answer in that tag to commit. Once five such people commit, the docs for that tag go live.

A better approach could be: 1. First let the users which have > (some threshold) rep from that tag propose an outline. 2. Once five such users prepare an initial outline (which can be partial), then all the users can start contributing to it. 3. If a user having rep < threshold wants to add a topic in the outline, he/she puts it a "bucket list", which one of the high rep users review and approve.

This way, documentation may become more structured. Once a (not so expert) user knows the topic to write on, I think they will start contributing faster and giving high-quality documentation. Even in the edit phase, it will be much more synchronized. Since all are discussing on a fixed list of topics, edits will be faster and of higher quality. Again, a new topic may not be added if most of the current topics need attention.

0

Certainly "traditional" means of imposing order on the contents of documents are not feasible in the context of Stackexchange Documentation. Let me propose a different "democratic" approach which would make any tedious editorial process unnecessary.

An author would assign previous and next topics to the topic he authored. His assignments would be worth 100 pt each. Users unhappy with author's imposed order could propose different place in document hierarchy and their assignments would be worth 1pt or 2pt depending on their rank. Of course weights given to author's and users' assignments may be completely different.

Certainly such collectively ordered Documentation will probably never be as coherent and logical as a work of a single author but I think it would be much better than what we have now.

4
  • You're confusing hierarchy and organization with browsing paths through the docs, of which there could be many depending on the reader's objectives.
    – user663031
    Commented Sep 20, 2016 at 12:37
  • You are wrong. If there is no subdivision of topics into sections, subsections etc. browsing order equals hierarchy.
    – helcim
    Commented Sep 23, 2016 at 6:18
  • I disagree. Robust documentation systems provide the feature of multiple browsing paths for different types of users and use cases.
    – user663031
    Commented Sep 23, 2016 at 7:08
  • Can you give an example of such a system? I think that's also possible to implement using weighted links.
    – helcim
    Commented Sep 25, 2016 at 18:56

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