🥁First strategy #webinar of the year: 31 January❗ Join @kvantomme to learn about how to build your #strategy for c… https://t.co/pTIjAapD7s
Community manager at Divio AG
Further reading: What nobody tells you about documentation (blog post)
Valuable summary of content types and relationships #APIthedocs pic.twitter.com/ayZ7kGDJsx
— Adrian Warman (@warmana) June 20, 2017
Technical writer, https://ddbeck.com/
Do not commit to near-future events, buy as much time as possible.
Plan:
Let users down easy:
Find Daniel's slides here.
A good landing is a landing you can walk away from @ddbeck #APItheDocs pic.twitter.com/MTqIvehIwd
— Kristof Van Tomme (@kvantomme) June 20, 2017
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.
At #APItheDocs @verythorough is discussing static site generators including @rl0rd's Slate.
— Nexmo (@Nexmo) June 20, 2017
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:
Results:
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.
GDS needs:
MVP just out (see on GitHub), next step is to meet the tech writer user needs not yet incorporated.
Further needs:
Prioritising is a challenge.
Creating consistent API documentation in government by @RosalieMarshall at @APItheDocs pic.twitter.com/mY2oZ3zNNI
— Adam Butler (@labfoo) June 20, 2017
#APItheDocs @RosalieMarshall contrasts writing for citizens (answer question, accomplish single task) vs. devs (understand complex system).
— Nexmo (@Nexmo) June 20, 2017
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:
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.
The most important documentation of an open source project is why the project exists @Ben_Hall #APItheDocs pic.twitter.com/ph9pU47oqV
— Kristof Van Tomme (@kvantomme) June 20, 2017
"The Art of Documentation and Readme.md" by @Ben_Hall from @teamKatacoda at @APItheDocs pic.twitter.com/C2WIKqpn2F
— Adam Butler (@labfoo) June 20, 2017
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:
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."
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:
graphql-docs
for receiving the actual schema.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:
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.
Transformations:
Advice to tech writers:
Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0
🥁First strategy #webinar of the year: 31 January❗ Join @kvantomme to learn about how to build your #strategy for c… https://t.co/pTIjAapD7s
We're excited to bring you the new virtual sessions of #APItheDocs focusing on the importance of #feedback #metrics… https://t.co/ifmptrM2bk
The #APItheDocs Virtual series returns in January, focusing on what is worth measuring on the community side of do… https://t.co/hS5D5ZzGg0
💡What are the essential elements of #developerportals? 💡How do you build a strategy that creates and catalyzes grea… https://t.co/5xstaoMV2w