What Nobody Tells You About Documentation

"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.

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

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.

Creating consistent API documentation in government

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:

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

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

The Art of Documentation and Readme.md

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.

Opening a Door to a Sleeping Castle

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).

Documenting GraphQL at 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:

Remove the old docs before running the build task.

Run a query on the GraphQL endpoint using graphql-docs for receiving the actual schema.

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.

How can API documentation be inherently agile?

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.