Category Archives: APIs
This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.
Ben Ahmady’s talk was “Write the API docs before the API exists”. The topic was DDD: docs driven development. Ben works at a company that has an API consisting of RESTful endpoints. The users are developers and program managers.
When Ben joined the company, they wanted to design version 3 (v3) of the API. To start off, they examined the problems that users were experiencing with the v2 API. They talked to product support and sales engineers, and looked at API logs and support tickets, to identify the pain points.
As well as identifying pain points, they wanted to make the API simpler to use: Simpler endpoint structure and request bodies, and default behaviour that was closer to user expectations.
Should a tech writer be involved from the start of a new project, at design stage? Ben pointed out that there are some disadvantages. For example, the design may change and the tech writer’s time thus may have been wasted. There are advantages too. For example, tech writers help ensure the design is consistent across different parts of the API.
Docs driven development (DDD)
The goal was to design a part of the API, and open it up for feedback in time windows. That is, provide a short period of time for feedback, then go back to design, and iterate.
They used GitLab for managing the docs (Slate) repository. Continuous integration (CI) was built in. Ben discussed some of the technical details. He also showed us the simplified requests that people can send to the v3 API.
Feedback on the resulting docs is positive. The team has also conducted some user research on the usability of v3. Some people find the docs important, but others prefer using Postman nearly entirely for experimenting with the API.
Overall, the project has been successful so far:
- Feedback is good.
- The use of GitLab CI and review apps has been very helpful, and will also be useful for future projects.
- The docs are ready to go at the same time as the API.
- The designers can focus on the whole experience.
Less positive aspects:
- It’s still difficult to get feedback from users.
- It’s hard to maintain v2 at the same time as v3. Ben has had to make the same change in each version of the API.
- Sometimes it’s hard for people to see what’s changed, so the team has to describe the changes made.
Ben and the team are planning much more user research and further design iterations. They’re also investigating new ways of getting user feedback.
Ben has learned a lot about various technologies, such as the OpenAPI spec, testing in different languages, such as Java, and GitLab CI.
The takeaway for writers is:
Plan carefully, and don’t be afraid of the tech!
Thanks Ben for an enthusiastic look at a cool, exciting way of developing docs and API at the same time.
We held the second Write the Docs meetup in Sydney on 2 March. The presentations were on moving into API technical writing, and the story of the Corilla documentation platform.
There was a good crowd at this meetup – around 20 technical writers descended on the Campaign Monitor offices in central Sydney. We were treated to a breath-taking 360-degree panorama of Sydney from the 38th floor of the building, and a couple of entertaining, informative, very different talks.
The recording of the session includes both talks, and is available on YouTube:
Presentation 1: Transitioning into API Tech Writing
The first presentation was from Priya Varghese, a technical writer at Google. Her talk was titled Transitioning into API Tech Writing. A year ago, Priya started work at Google as an API technical writer. Before that, she had many years’ experience as a tech writer for other audiences in the medical, security and education industries.
Priya talked about the questions she had before embarking on this new role, such as: How different is it from tech writing for other audiences? Do I know enough to explain APIs to developers? What if I don’t know how to code? Can API tech writing be fun? Her presentation gives an overview of APIs and the developer audience, the role of an API tech writer, the things you need to know, and the skills you need to acquire. One thing Priya strongly recommends is a mentor, and she finishes her talk by wondering if we should develop mentorship programs to guide and instruct technical writers.
Presentation 2: The Corilla Story
David Ryan, co-founder of Corilla, told the story of the development of Corilla and the forming of a startup. Corilla is an online documentation platform for technical writers, providing documentation authoring, publication and version-control tools. David’s talk was fun and educational, with intriguing glimpses of the roller-coaster ride of a startup founder.
David described how he and his team had the original idea for a new tool while working with a set of tools that was bloated, clumsy, and not designed for technical writing. Their new tool quickly became popular at Red Hat, where David was working at the time. With Red Hat’s blessing, he and his colleague branched out to form their own startup. And the rest is history. Two years later, Corilla is an alumni of the NUMA accelerator in Paris and has customers in more than 80 countries. Watch the video to hear David talk about the journey from then to now.
I’ve just published a blog post on the Google Geo Developers Blog, about a new design for the Google Maps API tutorials. I’d love some feedback from technical writers. If you have a few minutes, would you head on over there and let us know what you think?
Stack Overflow has recently announced the public beta release of its new documentation feature. That is, Stack Overflow now provides a platform for crowd-sourced documentation relating to any number of products, for the people, by the people.
For those of us managing the docs for widely-used products in particular, this means our customers may soon have access to an alternative, crowd-sourced documentation set.
What an awesome experiment for us as technical writers to follow! We’ll be able to see at first hand what our customers know they need, in terms of information about our products. Because this is Stack Overflow, the documented products are likely to be APIs, SDKs, and other developer-focused tools and technologies.
What if the documentation on Stack Overflow turns out to be voluminous and extremely useful – where would that leave us as technical writers working on proprietary doc sets? I think it will give us the opportunity to streamline our content, focusing even more than we do now on ensuring our information is up to date, and that our information architecture is the best we can make it.
In other words, we can ensure our target audiences can find what they need, even when they don’t know yet what that is.
Technical writing is hard. Information architecture is hard. The Q&A side of Stack Overflow works extremely well, because it focuses on short snippets of content that answer a particular question. It’s going to be very interesting indeed to see how well the new documentation feature works, with the more narrative demands of technical documentation.
An issue I foresee is that people will be tempted to kick off a topic, and then tire half way through and end up providing a link to the official documentation. Is that a bad thing? Tech writing know-how says our readers find it disconcerting to have to click around to find their information. It’s OK in a Q&A format, but not so good in a tutorial or step-by-step guide.
I really like Stack Overflow’s focus on sample-driven documentation!
I’d love to hear your thoughts on this development. Where do you think it’ll go within the next few months, and how about within the next two years? Will it fizzle into nothingness, or explode into something huge and beautiful? Will the original Q&A form of Stack Overflow merge into the new documentation form, becoming something new?
At the moment, I’m in the API docs meetup. The day starts with a few set talks, to be followed by “open space” sessions. Here are my notes on the first couple of talks about documentation tools.
Docbox and retext-mapbox-standard, from Mapbox
The first talk of the day was “REST API documentation generator” by Rafa of Mapbox. The Mapbox team writes the documentation in Markdown. In the background is Jekyll and GitHub pages. Rafa walked us through a couple of pages of the documentation, which includes code samples, generated for various programming languages, as well as hand-written words.
Rafa said this set of tools works really well for collaboration on writing the docs.
There was a lively discussion at Rafa’s session, with a very engaged audience. We discussed topics such as reader feedback, automated testing, size of the doc set, versioning, and more.
All this information was packed into half an hour! Thanks Rafa for a great session.
Tight coupling of API docs: YAML and custom tooling
The next session was “API documentation tooling at Capital One” by jennifer rondeau. Jennifer talked about the options and challenges for tight coupling of API documentation. Creating docs manually is not optimal. To keep your docs up to date, you need automated ways to sync your docs with your code. That’s what Jennifer means by “tight coupling”. In this talk, she’s focusing on the reference documentation, and specifically REST API reference docs.
You need to automate, but be ready for the areas where you need human intervention:
- Prefer a design-first rather than a code-first approach to creating an API. Jennifer’s team uses Swagger. For the most part, they use Swagger for naming conventions and exposing usable external APIs, not so much for the architectural considerations. Jennifer gave an example: Assume your development team creates a parameter that currently has only one permitted value. The parameter exists to allow for future expansion. In the external docs, remove the parameter.
- Note that Swagger YAML is human-readable, but not really. Jennifer emphasises that Swagger-UI is not a documentation tool. Swagger is most useful for generating server and client code. So, you need doc tooling. Jennifer’s team uses tooling that converts the Swagger YAML to a markup format (Markdown or HTML), and puts it all in a single file. Then there’s a manual step to clean up the text in the generated export files. You need to clean up the arrangement of the file, then expand descriptions and so on.
Jennifer walked us through the Capital One Platform documentation, and particularly the SwiftID webhooks, which is the output of the above processes. The hello world content is manually created. The source is all AsciiDoc, either generated from the YAML or hand-written. A member of the audience commented that it was good to see the manually-written content integrated with the generated docs.
Next, Jennifer discussed a different approach: creating documentation from tests. Jennifer talked about spring-restdocs, which adds the stubs for the documentation. You can then go and add the text later. How you automate your docs depends on how you’re building your API. The docs-from tests approach is useful particularly if you use the code first approach to creating an API. Your docs must exist in order for your tests to pass.
Thanks so much, Jennifer, for these tips on how to Swagger, and the hint about sprint-restdocs.