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:
- https://developers.box.com/
- http://developers.hubspot.com/
- https://developer.salesforce.com/
- https://developer.intuit.com/
- https://developers.google.com/
- https://www.dropbox.com/developers
- https://dev.twitter.com/
- https://api.slack.com/
- Static site generation (Jeykll)
- Markdown
- Automation/integration with ops/eng (continuous integration and continuous delivery)
- GitHub Pages
- CDN (optional)
- Discourse (http://try.discourse.org/)
- Automation/integration with ops/eng (continuous integration and continuous delivery)
- StatusPage.io (https://www.statuspage.io/)
- Automation/integration with ops/eng (continuous integration and continuous delivery)
- 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 (http://share.rockymadden.com/2v0k030k2W2r)
- Improved API documentation (swagger-ui or stoplight)
- Permalinks
- One source-of-truth documentation
- Conceptually simple solution
- Non-developer workflow friendly:
- GitHub inline editing (https://github.com/blog/844-forking-with-the-edit-button)
- GitHub file drops (https://github.com/blog/2105-upload-files-to-your-repositories)
- 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
- Non-developer workflow friendly:
- https://www.google.com/search?q=hipchat+integrations (Pagerduty and Intercom)
- http://share.rockymadden.com/1q1q451z1G0R
- Rocky's explanation:
- Having served as the lead SEO strategist for HealthGrades, a top-100 site by traffic in the United States
- Having solely developed several SEO centric properties that do 100x CE's traffic
- TODO