5

The Problem

In my opinion, Docs.SO is currently a good, standard-reference-style documentation. It works well to achieve its purpose as an updated, community-based, on-request source of answers.

So when public beta first came out, I was really excited — yay, I thought, now I can learn new languages and technologies in layman's terms from my fellow peers at Stack Overflow!

However, although each example is a mini-tutorial in-and-of-itself, the tags are generally an amorphous, unorganized topic cluster. If you're a prospective learner to a tag, the only indication of a learning path would be the "Overview" page in the dashboard, which is often some form of a "Getting Started" page. Then all goes to chaos as you browse the "all topics" tab, which is ordered not by order of learning but by votes.

Take, for example, the (a technology I am unfamiliar with) documentation: The Overview points to the Getting Started page, and then the all topics tab goes as follows:

  • Intent
  • Gradle for Android
  • Getting Started
  • ADB (Android Debug Bridge)
  • SQLite
  • et cetera...

What are "Intent"s? What is "Gradle"? "ADB"? "SQLite"? Besides the "Getting Started" page, this seems hardly suitable for a beginner in Android, like me.

I understand that Stack Overflow is not supposed to be a tutorial. I know there is a close reason against asking for a tutorial. It is meant to create specific answers to specific questions. Likewise, if you have a specific topic you want to look up in Documentation, you can do so. However, if a documentation is already set up with a pretty substantial amount of information, I believe it would only take a little bit of effort to rearrange it in a way that would appeal not only to experts in a specific topic, but novices as well.

In other words, this is not a suggestion to change the existing functionality of Documentation, but add another feature that appeals to a different audience.


My Proposal

Add a list of all of the topics for each tag. More specifically, this can be an extension of the "all topics" tab or an independent page of links:

  1. Create a different sorting system for the "all topics" tab. As of now, we have the "popular" and "active" options to sort the questions. Can we slide in a "tutorial" option?
  2. Or, create a tutorial list of topics. This can be placed under the "Overview" section on the dashboard, supplementing or replacing the common "Getting Started" pages. I'm imagining this to be something like Oracle's Really Big Index for its Java tutorials — just a list of pages, nothing too fancy.

By default, the pages would be included by order of votes, but it can be edited like any other Docs.SO page (edit proposal and reviewer accept).

I feel that the strongest argument against this would be that an order of what someone should learn would be highly subjective. It is, but this is simply a suggestion to the novice who just wants to get started. It doesn't have to be (and ideally cannot be, because of overlap) a definitive path, but simply a logical one.

I've never posted a feature request before, so I hope this proposal isn't too ludicrous. Any ideas?

5
  • 2
    "Docs.SO is currently a pure, reference-style documentation." No, it isn't. Commented Aug 6, 2016 at 17:55
  • @NicolBolas Edited. I mean, for standard cases of "How do I do this?", you can look it up (i.e., not a linear tutorial format). Commented Aug 6, 2016 at 19:02
  • 5
    Not a bad suggestion as such, but as long as Documentation seems to have no notion of an underlying structure that connects the various Examples, it doesn't make any sense to tack this on. Examples could be edited independently from each other, breaking the interconnection this feature would enable us to create. As it stands, Documentation isn't designed to be a book with chapters and the editorial oversight needed to make them.
    – Pekka
    Commented Aug 6, 2016 at 19:34
  • 1
    "What are "Intent"s? What is "Gradle"?" My exact same thought too. Context is missing, and there is not even a link to the corresponding tag (if one even exists). One has to manually find the tag, e.g. android-intent. Commented Aug 6, 2016 at 20:54
  • 1
    +1 for the idea of another "tutorial" view
    – TuringTux
    Commented Aug 10, 2016 at 8:32

1 Answer 1

4

Documentation is not a tutorial, and would be hard to structure like a tutorial.

Each example should cover a small amount of the content, the smallest unit one can have and not be able to break it down further (exception: the same thing in different versions I usually keep in the same example). And each example should also be general enough that it can apply to a wide variety of situations.

Topics merely exist to group related examples together. When a topic gets too many examples, it is usually a good idea to break it up. I suggest editing the Remarks section to link to the new section.

How does this relate to tutorials?

Tutorials can be thought of as collection of ordered steps, leading to a specific conclusion. Usually, they are too big and too specific to be a good fit for Documentation. It might be manageable to make tutorials with Documentation however:

  • Each step would link to one or more articles in Documentation, and a high level description would help you to tie those pieces together.

It might be better to use these "tutorials" as answers to questions instead of Docs in themselves, but I think it might depend on how the relationship between Q&A and Docs evolves in the future.

0

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