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.
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:
Docs needs of developers:
Too many user needs, no product answers them all. Decide by what they would build for GDS inside use, iterations on their own tool.
MVP just out (see on GitHub), next step is to meet the tech writer user needs not yet incorporated.
Prioritising is a challenge.
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.
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
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.
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:
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."
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:
graphql-docsfor receiving the actual schema.
Although the queries are self-documenting (based on the nature of GraphQL), technical writers have key roles in the doc generation procedure, such as:
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.
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.
Advice to tech writers: