API THE DOCS, LONDON
A one-day Write The Docs conference about all aspects of API documentation. Explore latest best practices, new trends, and strategies relevant to API documentation.
June 20th, 2017

What Nobody Tells You About Documentation

Daniele Procida

Community manager at Divio AG

  • "If you give insufficient documentation, the world may decide that your software is just too much trouble."
  • But there isn't the one documentation: there are four.
  • 4 types of documentation represent 4 specific purposes. Each one has one specific job and requires a distinct mode of writing, but there are gravitational pulls working among them.
    • Tutorials are learning-oriented and provide lessons that take the reader by the hand through a series of steps to complete a project. Tutorials are useful when studying and provide practical steps.
    • How-to guides are problem- and goal-oriented. They take the reader through the steps that are required to solve a problem. How-to guides are useful when coding, they provide practical steps.
    • Reference documentation is information-oriented, it includes technical descriptions of the machinery and how to operate them. References are useful when coding, they provide theoretical knowledge.
    • Discussions, also known as background topics, key topics or topic guides are understanding-oriented: they give explanations that clarify and illustrate a particular topic. They are useful when studying and provide theoretical knowledge.
  • The right way is the easier way, for both authors and readers. For authors, the 4 documentation types will define what to write, how to write it and where to put it. This distinction makes maintaining the documentation easier, and also enables readers to use the software more efficiently.

Further reading: What nobody tells you about documentation (blog post)

Daniele's presentation:

410 Gone: Documenting API Deprecations and Shutdowns

Daniel D. Beck

Technical writer, https://ddbeck.com/

  • Communication about how to cancel a project is under-represented.
  • As the tech writer, all your feelings about the deprecation are reasonable. But you cannot inflict them on your team or your users.
  • You have impact as a writer: it is important to get into the right mindset, plan the communication ahead in order to say the right things right.

  • Do not commit to near-future events, buy as much time as possible.

    Plan:

    • involve the operations and the support team,
    • stop the existing outreach,
    • list communication channels,
    • fit everything into an overall escalation strategy,
    • make a time schedule (use not-earlier-than-dates rather than deadlines).

    Let users down easy:

    • be aware that you and your users might experience the shutdown differently,
    • explain what happens when and what is the user to do,
    • offer alternatives, give users an exit,
    • do not necessarily explain “why” the shutdown happened nor show any hesitation. This is not the time for subtlety or being cool (even if that is in your general styleguide),
    • show gratitude.

Find Daniel's slides here.

Daniel's presentation:

The Best of Both Worlds: A Git-Based CMS for Static Sites

Jessica Parsons

Developer Support Engineer at Netlify

API documentation is necessarily a collaboration between technical writer and developer, but merging their disparate workflows can be a challenge.

Content Management Systems (CMS) are feature-rich, widely used tools to edit and update content without touching code. Their downside is that the content and the development workflow are separated.

With Static Site Generators (SSG) documentarians are able to write by following the dev workflow, e.g. storing documentation in a Git repo, using branches for modification. Hosting is (mostly) free and the content is separated from the tools. There are many SSGs, some made specifically for documentation: Sphinx, MkDocs, GitBook, Slate (API docs generator). The downsides are that content must be written in code and they are not as full-featured as content management systems.

Netlify CMS helps bridge this gap between CMSs and SSGs, by providing a simple UI wrapper for Git functions, with a real-time markdown preview. Netlify works with the GitHub API, uses Markdown for content and provides an editorial workflow.

Find Jessica's slides here.

Jessica's presentation:

Creating consistent API documentation in government

Rosalie Marshall

Technical Author at GDS

Main goal of GDS is to build government as a platform. Developers need to be able to integrate without wasting time on deciphering poorly written documentation. Encourage code sharing and use of open source software by providing strong documentation.

Research on API docs needs for GDS:

  1. Testing with 30 technical architects and developers:
    • opinion on existing docs sites in and out of GDS
    • card sorting and diary studies on all docs they read in a week
  2. Asking companies like Stripe and GoCardLess on what they did to make their API docs a success.

Results:

Docs needs of developers:

  • up to date
  • right version
  • searchable and scannable
  • understand scope quickly
  • colour-coded blocks of code
  • working examples
  • direct linking to parts of the docs

Too many user needs, no product answers them all. Decide by what they would build for GDS inside use, iterations on their own tool.

GDS needs:

  • version control
  • self-hosting at gov.uk
  • auto-testing of code samples
  • consistent one look for all GDS docs, a tool that fits both API docs and general manuals
  • use GovSpeak, a GDS-flavoured markdown: warning callouts, numbered lists etc.

MVP just out (see on GitHub), next step is to meet the tech writer user needs not yet incorporated.

Further needs:

  • separate product for Verify, that is not API documentation
  • a slackbot for reviews
  • markdown or not (new team-members joining)
  • openAPI specification (ongoing)
  • moving the various API references from Gelato over to their new product

Prioritising is a challenge.

Rosalie's presentation:

The Art of Documentation and Readme.md

Ben Hall

Ocelot Uproar

Whole new ecosystems arise around new technologies, which means we all have a lot to learn. "Documentation is helping developers to have more comfort with how they approach new technologies."

What is the art of documentation? The user journey begins long before landing on the docs site. How can we make the learning journey be more integrated into the product experience, to make it less explicitly a task? We need to find the developer's flow channel with our documentation: not too challenging so we do not trigger anxiety, but not too simple either because then it would be boring. Research results show that teaching others/immediate use gives the highest retention rates when learning.

Stage 1: Discovery. Where users decide wether to use the product. At the starting point users don't know anything of the product, so we need to be very clear and concise with the opening tagline. Generally build on experiences to express what's happening within the product. (Example intro lines from: Kotlin, Calico, Kubernetes) No need for an outrageous markting pitch at this point.

Stage 2: Getting started The user has a dream of how the product will make their life perfect, so we want to prove that. Good example: Stripe. Build up confidence and trust that the product will solve the user's problems. Problem: no interactive possibility on mobile/iPad, they would loose out on the journey.
Good example of learning while starting: OpenShift Origin, GO.

Unintentional blockers:

  • broken/incomplete samples are very frustrating
  • source-code-only releases make it much harder to start
  • video content: too deep or too wide explanation takes out of the flow and even a small change needs a complete update
  • jumping over the gettings started steps

Stage 3: Problem solving Show a prototype for what can be achieved, give working examples. Give seamleass options for adjustments in the code snippets so the exploration flow is not broken. Be very straightforward. Catch people on their leaning journey with these good practices before they become disillusioned of the product.

Stage 4: Guidance

  • Tutorials, how-to guides, discussions.
  • Take the user to be an expert.
  • Good example is WeaveWorks, Twilio. Take users to the most relevant documentation with seamless choices.
  • Slack: you can edit/modify code snippets and get a preview what the result would look like.
  • Community: show how they use the product and involve them to catch the long tail. See Digital Ocean.

Stage 5: References Readme.md is your gateway to the product, it sets the tone and show what the product is good for. Most importantly, tell why the project exists at all.

Building community: Need to include the contributor guidelines, license and where to discuss the project. It is possible to build a community around the documentation itself. Good examples: Kubernetes sig-docs, Docker docs hackathon. Contribution has to be simple. Github is not too friendly for small changes, but you can work around that.

Ben's presentation:

Opening a Door to a Sleeping Castle

Jaroslaw Machaň

Erste Bank

A talk about the APIs built in Ceska Bank (Erste Bank in Czech Republic ) and the story behind. How do banks go about in the digital transformation age? An API platform then an API economy has to be built for a bank to survive the coming years.

With 10k employees and thousands of processes behind, change is hard and slow. "In every big corporation there must be some islands of positive deviation who could break this."

The main motivation to build an API platform wasn't PSD2 but the developers (internal and 3rd party). Need place for rapid prototyping. 2 years ago switched to agile dev cycles.

Prerequisites for being ready for PSD2:

  • Long-term based high quality relationship with outside community.
  • State of the art applications, comply to world wide standards (not local).

Ceska Bank's Dev portal:

  • Focus on the developer experience.
  • Single page application, showing the 6 APIs meant for 3rd party developers' use.
  • API documentation written in the Apiary platform.
  • First bank in the world to release SDKs for their APIs.
  • Keys via registration or use the sandbox.
  • Sharing and co-operating with community.

Created Gustav in 2015 to show developers where to start with Ceska Bank APIs. Still working, open source banking app.

Q&A with interesting background stories.
"You have to challenge your business."

Jaroslav's presentation

and slides

Documenting GraphQL at Shopify

Andrew Johnston

Shopify

At a company like Shopify, API management doesn’t know what the clients exactly want. They know that clients search for products, but a product has several properties that the clients may or may not need in their specific case. GraphQL helps Shopify to only return the data that is needed.

They use Jekyll static site generator for building up their documentation, in three main steps:

  1. Remove the old docs before running the build task.
  2. Run a query on the GraphQL endpoint using graphql-docs for receiving the actual schema.
  3. Generate HTML files from the schema. The files are structured into folders representing the navigation. The changes in documentation can be seen using git diff.

Although the queries are self-documenting (based on the nature of GraphQL), technical writers have key roles in the doc generation procedure, such as:

  • complementing the raw GraphQL schema with descriptions (Facebook’s Graph API documentation was a great example for their writers),
  • writing educational materials for user onboarding.

Need detailed conceptual docs to become familiar with the specific business domain, and to build up some confidence making queries and mutations. Once you are there however, you don't need reference docs anymore.

Andrew's presentation

and slides

How can API documentation be inherently agile?

Jennifer Riggins

Jennifer explores then contradicts that documentation is inherently un-agile: she shows many examples and quotes opinions on how docs fit in the agile circle.

Documentation is the number one thing API consumers want, it is the basis of their decision-making. In the world of micro-services and containers, everything has to work together and although documentation is less likely to happen it becomes more and more necessary.
Early-on docs allow prototyping, simpler code and true collaboration.
Your documentation is your SEO. It has to say what your API does.

Transformations:

Advice to tech writers:

  • Create a style guide then get the devs document their code.
  • Template, checklists.
  • Automate.
  • Docs have to live alongside the code to stay up to date.

Jennifer's presentation

and slides

Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0