Information architecture of Stack Overflow’s documentation feature

A couple of days ago I pondered on the effect Stack Overflow’s new documentation feature may have on technical writing. Now I’ve taken a closer look at what goes into a topic and how topics are organised.

At first I found Stack Overflow’s documentation feature a little confusing, both as a reader of the docs and as a potential contributor. I thought the organisation wasn’t “intuitive”, by some definition of intuitive. A deep dive has helped me understand the structure offered by Stack Overflow as a documentation platform. It’s less complex than I’d expected. That’s probably why I couldn’t grok it at first!

TL;DR: Topics are grouped under a tag, such as “CSS” or “Java Language”. A tag represents something that needs documenting. The subject of the tag can be as big or as small as you like – or rather, as big or as small as the community likes. Topics are linked together by the tag and by hyperlinks.

What does a topic look like?

When you create a topic, Stack Overflow offers you an outline to fill in. A topic has the following parts:

  • Topic title
  • Examples – that is, code samples
  • Syntax – a place to call out the most important bits of the code, particularly signatures
  • Parameters – that is, method parameters
  • Remarks – anything that doesn’t fit into the above sections

Here’s a screenshot showing the first few parts of a new topic, titled “Find directions”, in edit mode. There’s some useful contextual help for the topic author.

Stack Overflow documentation - topic creation

I like the fact that code comes first, given that the products being documented are developer products such as APIs and SDKs. On Stack Overflow, the audience consists of developers. A good code sample gives developers context and is often all the developer needs to be able to use the product.

On the other hand, it’s interesting that the “remarks” section is right at the end of the topic, and that it’s called “remarks” rather than something a little more weighty or alluring. Even the ubiquitous “more information” would convey… well, more information about what this section is intended to contain.

Code samples are great, but developers often do need other types of information: conceptual content such as an introduction, typical use cases, overviews, best practices, and more.

How do people tie topics together?

How do readers get a complete view of the entirety of a particular subject on the Stack Overflow documentation platform? Actually, taking a step back, I find myself wondering what that “entirety” might be. It’s up to the community to define the size of the things that are documented, and how those things fit in with other things, big or small.

Documentation is attached to tags on Stack Overflow. These are the same tags as are used for the original Q&A part of Stack Overflow. The tag is the primary mechanism for organising topics. For example, the classic Stack Overflow has a “CSS” tag with tagged questions, and now with tagged documentation topics too.

Note that there’s also a more specific set of CSS3-tagged questions and CSS3 documentation topics, and indeed many other CSS-related tags.

For each tag, you can see the set of available topics on the “all topics” tab, like this list of topics for the CSS tag:

Stack Overflow documentation - list of topics

As a reader, you can order the topics by popularity or by date last modified.

There’s an overview topic for each tag, which in this case is titled “Adding CSS to a Document“:

Stack Overflow documentation - overview topic

Each tag also has a dashboard, which shows requests from the community and changes that need reviewing. If you’re a contributor, you can use the dashboard to manage your own activity. Here’s the dashboard for the CSS tag:

Stack Overflow docs - CSS

As you can see on the dashboard, people can suggest new topics and contribute to existing topics. There are currently 41 topics tagged “CSS”, and 4 requests for new topics. People can also mark a topic as needing improvement.

Getting around the documentation

So, in summary, topics are linked by tags. You can also cross-link within topics, using hyperlinks as is standard in web-based documentation.

The only table of contents is the list of topics on the “all topics” tab for each tag. There’s no other type of navigation, such as a curated left-hand navigation or top-level menu.

As David Vogel remarked, this could lead to interesting new information architecture models. I think there’s room here for Stack Overflow to adapt the new platform in response to the way people are using it. Larry Kunz commented that technical writers can keep an eye on this development to learn more about SEO and findability.

Stay tuned!

What the community thinks of the documentation feature

There’s plenty of discussion, much of it heart-felt, about exactly what documentation should be, and hence what Stack Overflow as a doc platform should look like. Here are a couple of examples:

In conclusion

If Stack Overflow has the resources to put into it, they’ll be able to adjust the new documentation platform to suit the needs of the community. As technical writers, we’ll be able to watch and learn. Exciting times.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 24 July 2016, in technical writing and tagged , , , . Bookmark the permalink. 5 Comments.

  1. Hi Sarah, excellent article! It is dizzying to observe the evolution of Stack Overflow. Clearly it is something people are very passionate about which is quite a boon for those of us working on programming documentation! As you know, we are attempting to create our own space in the Stack Exchange ecosystem which covers all aspects of documentation. This was inspired by the Stack Overflow documentation initiative and from observing other sites on Stack Exchange. I appreciate your participation!

  2. Here’s an update from SO’s initiative: http://meta.stackoverflow.com/questions/329557/documentation-update-july-25th?cb=1

    I guess I wasn’t the only one who was shocked by all the activity!
    ———————————
    What we’ve learned

    1. Ho-boy, lots of contributions. We got more activity in 1 day on Stack Overflow than we did in the entirety of the private beta. Lots and lots of bugs that didn’t come up in our (months of) private testing. Accordingly, since Thursday we’ve been focused on bugs.
    ———————————

    • Hallo David,
      Thanks for the link! I particularly like the feature request to cross-link tags. That will help with navigating around related topics.
      Cheers
      Sarah

  1. Pingback: Stack Overflow’s documentation should be called samples | ffeathers

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: