What Makes A Great Developer Hub?
What Are Developer Documentation Hubs?
A developer hub is a platform for connecting with and supporting developers building on your platform. Common features include documentation, tutorials, support, FAQs, key generation, app management and more. Still not sure? Basically, anytime you see docs.site.com or devs.example.com, that’s probably a developer hub. Developer documentation hubs allow companies to scale quickly – a well-documented API is the best bizdev hire you can possibly make at an early stage. Having an API helps scale your business. Cristina Cordova, Business Development & Partnerships at Stripe, has spoken about this, and it is further explained in Pitching & Closing by Alexander Taub, CEO and Founder of SocialRank and Ellen DaSilva, Business Operations at Twitter.
The most common component of developer hubs is documentation, which (should!) be split up into three common components:
- Tutorial (How can I do XYZ?)
- People refer to tutorials, and want to receive quick highlights.
- Include thorough details. Cover a wide range of challenges and use cases. If developers encounter a difficulty during an introduction to a tool, they may easily abandon their efforts.
- Engage emotions. People want products that make their lives easier. Explain the different use cases, so they understand the benefits.
- Good tutorial example: Ruby on Rails
2. Topical (Why would I want to do XYZ?)
- Provide in-depth explanations. Good topical guides explain the philosophy behind the software, and provide high-level answers to “how” and “why”. After reading tutorials and understanding the overarching themes, there should be resources providing the details.
- Good topical examples: Django and Coinbase
3. Reference (How does function/method/endpoint XYZ work?)
- Lots of documentation online exclusively relies on tools that generate documentation from the source code. It makes it easy, however it is the equivalent of handing someone a dictionary and telling them to “learn English”. It’s great for looking things up, but bad for learning.
- Good reference examples: jQuery and Reverb
Most developer hubs are minimal, and only contain one or two of these categories. Developers are tasked with the grunt work of establishing the foundation for a startup, and look for ways to prioritize their to-do list. The core product takes up most of the time, and companies are lucky to find resources to create an API. This makes creating thorough developer documentation an afterthought more often than it should be.
In an ideal world, community is a fourth component to good documentation.
- Comments — developers can share feedback.
- Suggest Edits section — designed like a GitHub pull request.
- Support section — ask questions, which are cross-linked so you can see relevant questions under the documentation.
Why Do Companies Need APIs?
- Sharing APIs is a way to share code that you’re developing. You create and contribute to your community by sharing your API.
- Companies can leverage their API for monetization.
What Are the Best Documentation Hubs?
- ReadMe covers the standard three developer doc components, along with the bonus community feature. It also automatically updates the developer code to the organized documentation framework, so it does not become out-of-date. It does this without being generated by the code, because it would feel too mechanical.