Maybe it’s time we re-think docs

Image source: Flickr via creative commons

From static and stale, to engaging and interactive

Today, too many documentation sites are static, out-of-date, and lifeless. They aren’t thought of with the same care and detail as the core product, even though they often are a core product. The reader is expected to do too much work, open tab after tab, search endlessly and scroll through verbose articles just to find a simple code example.

  1. People have a hard time finding what they need: Documentation is not linked from the right places in the product.
  2. Support teams rely on a knowledge management system (KM) that duplicates the docs instead of referencing them — focusing on content storage, retrieval, and assessment (instead of end-user success).
  3. Developers learn different things in lots of different ways — tutorials, videos, examples, guides, etc. Docs today mostly offer static content with code examples that aren’t interactive.
  4. People use search as a way to navigate, and they often lose the search UX when they’re deep into an article.
  5. When developers get stuck, they want to ask other developers questions & get an answer from their peers.

Some guiding principles

After talking with hundreds of developers, learning what they were struggling with, and what they wished for, I wrote up a few principles. The intent was to have something to lean on, that I could use as I brainstormed ideas that may solve some frustrations developers have with documentation.

  1. Lead with code: Developers want to write code, give them the code examples as starting blocks. Don’t bury the lede.
  2. Solve the problem (aka: answer the question): Developers come to docs to learn the answer to a question, challenge, or problem they’re trying to resolve. Give them the answer through multiple methods (video, text, tutorials, guides, etc.), so they learn the solution in a way that works for them.
  3. Enable community: Embrace the fun of collaboration, the support of the community, and empower people teaching people.
  4. Meet user's needs: Docs should never be optimized to result in a support ticket, we don’t funnel devs to open tickets, we ensure our content meets the user’s need.
  5. Encourage contribution: Open source — anyone should be able to contribute to docs & help improve the content.
  6. Keep docs fresh: Software changes, so should the docs! They should feel alive, fresh, and relevant.
  7. Refine and simplify: Simplicity is hard to achieve, we consistently refine and simplify our platform and access to content — minimize the clicks to content.
  8. Measurable success: We are actively measuring if our content successfully meets users’ needs and consistently improves its efficacy.
  9. Encourage play and experimentation: Developers come to docs to do many things, let them discover and engage creatively through playing around. “Try it yourself!”
  10. Medium agnostic & portable: Developers should be able to call docs from wherever they are, like their terminal or their IDE. Code examples should be easy to take with you and re-use.

Brainstorm and sketch

This next part is a little peek into the brain of a product person. What follows are a series of ideas — some of these are provoking actual improvements to GitHub’s docs, but I use them as a way to spark curiosity and generate ideas for how we can build better docs for developers in general.

  • Mobile views
  • Reference a doc from within another GitHub property (, community forum, etc.)
  • A more fun, and intuitive home page

A new tutorial/guide page

A place to have a conversation

Learn in more ways than one: adding video

Finally: Search and navigation

  1. Organize content based on so that navigating to the right content feels effortless.
  2. Make text legible.
  3. Be simple, predictable, and consistent.

Find your answer, faster

The entire motivation for exploring these sketches is to build a doc experience that meets developers where they’re at. can do a better job of organizing the content, giving you new ways to access it, and customizing a reading experience that is designed for you. Developer documentation is part of the product, an extension of the application, and a part of the code. Without it, people can get lost, so it’s important to give waypoints and that’s what this system is intended to provide. The more magic “aha!” and “it worked!” moments that we can inspire through documentation, the more we’re unlocking a path for people to be creative, productive, and get back to the business of coding.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Kathy Korevec

Kathy Korevec

Currently working as a VP of Product at Vercel. I write a lot about Product management and building developer tools.