Skip to content

Instantly share code, notes, and snippets.

Forked from greglindahl/
Last active February 23, 2016 20:57
Show Gist options
  • Save rockymadden/b8ca9adbe7f96b672592 to your computer and use it in GitHub Desktop.
Save rockymadden/b8ca9adbe7f96b672592 to your computer and use it in GitHub Desktop.
Developer Portal pitch

The Pitch

Let's move to a modern approach for our developer documentation and, generally, improve developer experiences by creating a focused developer portal. Let's unify our documentation efforts, use documentation to reduce customer success needs, use documentation to improve experiences, and create a one-stop-shop for anything a developer might need. Additionally, lets make it conceptually simple and easy to maintain and support. This idea is not new, in fact nearly every modern API company uses this approach:

The How


  • Static site generation (Jeykll)
  • Markdown
  • Automation/integration with ops/eng (continuous integration and continuous delivery)
  • GitHub Pages
  • CDN (optional)

Forum (eventually)

Status (eventually)

The Why

Improved third-party developer experiences

  • One-stop-shop for all developer needs
  • Clearer, more focused, navigation
  • First-class UI/UX experience
  • Ability to search docs
  • Richer documentation approaches (not limited to the plugins/approaches in Wordpress)
  • Open source (fix a typo you see, contribute a new doc, ask for a doc to be created via GH issue)
  • More responsive and performant, as it is statically compiled
  • Less error prone, with errors detected at compile time (
  • Improved API documentation (swagger-ui or stoplight)
  • Permalinks
  • One source-of-truth documentation

Improved internal developer experiences

  • Conceptually simple solution
    • Non-developer workflow friendly:
    • Developer workflow friendly:
      • Git/GitHub
      • GitHub flow branching
      • Push to update docs
      • Pull requests oversight by project maintainers
    • Essentially just markdown files that are made into our doc site via Jekyll
      • We are not pinned to Jekyll, unless we wish to be (Markdown files are the "database")
    • Static site compilation means that essentially our docs site is just a set of HTML, JS, CSS files that can be hosted anywhere
    • Static site generation means you can run and develop against the developer portal on your local machine (Jekyll)
      • Try before you push
    • Using GitHub pages means we don't have to worry about any hosting, scaling, or cost
    • Using GitHub pages means we can have a customized domain
    • Using a CDN in front of GitHub pages means we can use https and have all the benefits of a CDN
    • Greg, serving as project maintainer, is completely self-sufficient
    • Easy to debug, since errors happen at compile time and not run time

Improved SEO

Improved Internal Sales and Marketing Support

  • TODO
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment