I originally posted this in the documentation beta, but it got no response and almost no views there. I'm not sure if it's because few people are monitoring the documentation beta or because the topic of the post is not a major concern. Anyway, I deleted the original post and I'm reposting a slightly modified version here. I hope that isn't a no-no.
I'm excited about Documentation and what it has to offer, especially the prominence of the examples. This has the potential to be very, very helpful to myself and other developers struggling to implement under-documented or outdated topics from the official documentation.
I now see the benefit of this beta, though. The following are some of my thoughts about how the structure of the Documentation could be improved (in my opinion).
Related questions
I realize variants of this question have come up before:
I'm writing a new question to bring renewed focus on this and to propose a more hierarchical structure.
The Problem with the Current Documentation Topics Structure
As new documentation topics are starting to trickle in, they tend to be very broad. The examples, however, are more detailed. Take, for instance, Android Layouts (and this is just one of many broad topics that currently exist):
Right now this organization looks quite nice because there is only one example per subtopic. However, let's just say I think I (or if not me, then 10 other people in the future) might be able to make a better LinearLayout
example than the current one. Soon this topic will become a mass of LinearLayout
, RelativeLayout
, and WhateverLayout
examples that are ordered not by layout type, but by the number of votes. An unfortunate mess.
Why We Don't Currently Have a Hierarchical Structure
In Warlords of Documentation: Your Quest(ions Answered), the authors stated
What about hierarchies, nesting, grouping, namespaces, modules, etc.?
This question was asked a couple of times, but there was also a point raised a few times which is basically its answer: the default way people search for and through documentation is they google it.
...
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.
What is super important is linking. Lots of information is conveyed, and links are very flexible. We intend to strongly encourage links, and to make intelligent “Related Topic” inferencing based on it.
So the current plan is googling and linking. If linking can be well enforced, then it will be at least a slight improvement over over the current Stack Overflow Q&A format. However, googling only works if Google shows me the topic I am looking for. That is definitely not a guarantee. Also, neither of these things deal with the problem of overly broad topics or with organizing the random variety of topics that will accumulate over time.
Benefits of the Official Documentation
The benefits of the official documentation are
- It is exhaustively thorough.
- It is logically organized into a hierarchy of topics.
That means that even when Google doesn't give me anything, I can look it up manually in the documentation tree. I'll do whatever is fastest, of course, which means google first, go to the hierarchy second.
To me it seems that our Documentation as it currently exists is not significantly different than the Q&A. If Google doesn't show me and I didn't happen to run across a link from a similar topic, I'm left with nothing (even if the topic/answer actually does exist). But that's what its always been like with SO Q&A.
By using a hierarchical structure in our Documentation, we can have the best of both worlds: a browsable structure on every topic users need + practical up-to-date examples.
Renewed Proposal to Implement a Hierarchical Structure
Benefits
Enforcing new topics to fit into a hierarchical structure would give the following benefits:
- 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.
Challenges (and potential solutions)
What hierarchy should be used?
- API related documentation should follow the structure of the official documentation tree and change as the official tree changes.
- Tutorial-like material (“Getting Started,” “Making HTTP Queries,” etc.) could follow a general outline used across Documentations but be customized according to the needs of a particular Documentation.
How do you modify the hierarchy?
- Someone (because of stated reason x (ie, official doc structure has changed) makes a request to
- create a new sibling topic/level or sub-topic. This doesn't create content, just an empty (greyed-out?) spot in the tree structure.
- move a sibling topic/level or sub-topic to a new location
- delete/deprecate a topic
- rename a topic/level
- Other people must approve the change. The bigger the change, the more high rep users are needed to approve it.
- Someone (because of stated reason x (ie, official doc structure has changed) makes a request to
Who can modify the hierarchy?
- Anyone can add content to a requested topic.
- Anyone of a certain rep can request a change to the hierarchy structure.
- A relatively high number of high rep users are needed to approve the changes.
What happens to Topics when the hierarchy is modified?
- The individual topics themselves can be stored as they are now or as Stack Overflow question pages are stored. However, they should be internally linked to the hierarchy and that hierarchy should be visible for browsing from the topic page.
- Parent moved: move the subtopics also.
- Parent deleted: delete, move, or merge subtopics.
- Parent renamed: do nothing to subtopics unless necessary.
Isn't this just encouraging people to recreate existing official docs or make trivial additions?
- You can't add content without a topic request
- People only get rep for examples
- Trivial examples can be downvoted
Summary
Creating a hierarchical structure will be more work in some regards
- Creating an initial hierarchical outline
- modifying the hierarchy
But it will save an untold amount of time in other areas
- Checking for, marking, and merging duplicate topics
- Finding the topics needed when Google fails
We have the opportunity to start now before the Documentation topics become unwieldy. It will be more work up front but in the long run I think we'll be glad we did.