I’m at Write the Docs today in Budapest and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Shwetank is a web evangelist at Opera. He’s worked there for 6 years or so now and is the main author of the Opera Extensions Docs.
A year ago Opera moved their platform to Chromium. Their extensions platform switched to accomodate chrome.* APIs. They had to either re-document everything from the ground up or take Google’s existing docs and improve them. Both were difficult options. On the one hand it would be hard to re-create something. On the other it’d be difficult to improve upon an already great product: Google’s Docs. Ultimately they took a look at Google’s Docs to see what they could improve.
What needed to be communicated in these docs was Opera’s architecture, extension APIs, and AddOns Store. The aim was to be easy to understand and to explain the most common use cases.
As an extensions developer himself Shwetank could empathize with what the users of this documentation would need. He ran in to many hurdles in trying to understand the platform and documentaed the solutions he found.
They set the scope of improvement upon Google’s Docs to be:
- Unified architecture explanation
- Easy to follow tutorials
- Explaining common use cases
- Simple sample extensions
The architecture needed to be explained on one page. The tutorials for essential APIs and functions needed to be accessible to new developers. Docs needed to cover a breadth of common uses, such as closing and opening tabs.
The core of this improvement process relied on making sample extensions for common use cases. By documenting the issues Shwetank came across he was then able to write an article which improved upon Google’s core docs.
On the technical side of things they built the site in Jekyll while using Markdown for the tutorials and an API Docs in plain HTML. It’s available on GitHub.
Sample code must be as simple as possible with as few lines as possible. It’s a starting point to build from, not an exhaustive source of implementation. 20 pieces of sample code that each do one thing is better than one monolithic code example that does 20 things.
One thing that worked well for Opera after publishing the new docs was using multiple channels for feedback. They heard from people on Twitter, email, and Stack Overflow. Much of the feedback was about abstract scenarios.
Still to come in the docs is an improved navigation, boilerplate extension generator, translations, and adjusting the tone.