Designing Docs for Developers
Last week we re-designed our documentation, primarily in terms of organization and content, but we also made the visual design fit in with our homepage.
I decided to write about our experiences to get your feedback to inform future updates and also to share the recipe we came up with for designing docs for developers.
What do you think of the results? How do you like to see docs organized and presented? Our current recipe is:
- 4 top-level categories
- 3 questions the front-page must answer
- No social features or promotional materials
It’s a work in progress and we’d love your feedback. Here’s what we changed and this is how we think about designing docs for developers.
Here’s where we started from…
The good news was that we knew the very basics of the content were sound – plenty of users are building on our platform using this content.
But we could tell something needed to change since we were getting support requests that seemed to point to a difficulty finding the right information with this design. Also, we found users who were unaware of our blog and the various screencasts and tutorials that we post here regularly.
Just as important as existing users looking to find the right information fast, are new visitors looking to explore the capabilities of the platform to decide if it would be a fit for them. We knew it’s important for us to make that exploration process as simple and fast as possible.
What we did
Fewer top-level categories
The original docs had 14 top-level categories on the left, which we consolidated to 4. It’s easy for categories to build up as you add major features and new content, which we’ve been doing very regularly. So we reorganized all the content under just 4 reflecting the mainline use-cases:
- Get Started: instructions for new users
- API: explore the capabilities of the platform
- Tools: details of how to interact with the tools
- Recipes: how to build apps using the platform
While the first three are absolutely necessary, the ‘Recipes’ category could be the most important. It’s all very well to have the ability to perform various tasks with the platform, but the magic happens in putting it all together into a rich application.
It’s always tempting to let the number of top-level categories creep upwards. What about a support category? What about external links to relevant content like the App Store submission process?
We found other ways to include those in the main body of the content where relevant. We elected simplicity.
Visual design fitting in with homepage
We had recently redesigned our homepage and had seen immediate results with a 1.5x increase in time / visit and pages / visit.
So we applied the same, clean design to the docs – that required a little bit of work since we use Sphinx to generate the docs and host them with readthedocs.org. I used the assets we had for the Trigger.io homepage to modify one of the Sphinx themes.
Simple but useful docs front-page
Our goals with the new front-page were to answer 3 questions:
- How can I get help: we put prominent links to our StackOverflow tag and our email
- How does a new user get started: we boiled the answer down to a 3-step quickstart
- What are the capabilities of the platform: we provided a table of the main API modules allows for a quick scan
And to do that in less than 800px of height.
What we didn’t do
Some documentation spends too much time in the preamble of why you would want to use the product. In our view that’s best handled by the main website and there is no need for repetition.
If you’re looking at the documentation you want to see the details and quickly find the best points to dive in at depending on your interests, skill level, and how much time you’re going to spend.
So we didn’t waste any time or space on the benefits, differences with other platforms, or the details of how the technology works.
Our blog and other pages such as Catalyst contain social links in a sidebar on the left – subscribe to newsletter, follow on Twitter, like on Facebook. We love you guys and want you to share when we show you something interesting!
But when I look at docs, I’m either making a decision on whether to sign-up or not, or I’m looking for a specific piece of information so I can get back to developing. Most likely with my headphones on. Not in a sharing mood.
There’s plenty of things we’re still working to improve.
For example, I’d like to make the Quickstart guide more visual and guide you through the process across different pages – Parse does this really well. We’re also thinking about a “kitchen sink” app to go along with the docs so you can see the features in action without writing a line of code.
Most important of all will be sticking to our design approach as we continue to add to the capabilities of the platform and add recipes. We hope you keep us honest…