by kvantomme / 6 March, 2018



Meet Kristof in London, where he will attend a Write the Docs meetup about how to develop and manage your career in documentation.

Details

Writing technical documentation is so much more than just writing. There is a wide variety of tools, skills and experience required for different roles and these requirements vary not just by job, but also change over time. As documentarians, we often have to take responsibility for our own development and learning. At this day-long conference, organised in collaboration with GDS, we will hear from those who have gained new skills, and discuss how to manage and develop your career in documentation.

Agenda

09:30 - 10:00 Arrive and sign in

10:00 - 10:15 Introduction

10:15 - 10:45 What... Read more

by laura / 1 June, 2017

The annual North-American Write The Docs conference this May featured 2 API documentation redo presentations:

Lyzi Diamond described Mapbox (formerly a part of Development Seed) documentation automagic in detail, Sarah Hersh talked about the journey that NPR One undertook towards a new task-based approach for their API's developer documentation.

In this post we aim to give you an account of these presentations, plus a little extra takeaway.

Lyzi Diamond: Testing: it's not just for code anymore

Lyzi Diamond from Mapbox showcased the use of docbox on their own documentation, through remark and retext. Lyzi showed why it works for them to test everything.

The story started in 2015, December, when Mapbox had a confusing TOC for their developer docs. They... Read more

by kathleen / 23 December, 2016

The main purpose of Platform Software Development Kits and Helper/Client Libraries (we’ll use “SDKs” to address these collectively in our writing) is to accelerate and simplify development. A well maintained SDK is a trust signal that indicates the level of support and usage of your API for a language, framework, or development platform. So indirectly SDKs work as social proof, that indicates how many communities are already using your API.

In this post, we’ll look at how the developer portals in our research sample included SDKs. We’ll examine their functions, describe where we found them in the site architecture and deduct best practices.

We’ll discuss what kind of SDKs the Portals in our sample used. We’ll analyze their choices and evaluate them against the... Read more

by kvantomme / 24 November, 2016

Last week, I presented an evolved version of my "AI the docs!” talk. This time with the subtitle “Conversational UI, Embedded Help and Artificial Help. A fertile ground for minimalism and DITA" at CIDM's European DITA conference in Munich, 2016 November 14-15.

Video recording:

I started my talk from the same base concepts as my talk at Write the Docs Prague, but the structure was much better and there were several new insights that I think can be valuable if you are considering the space.

In my talk I focussed on:

why teaching through conversation is back and why I believe this is the future of documentation, even if manuals will remain relevant and never completely go away.

3 trends that drive the need for AI in the documentation space... Read more
by kvantomme / 16 September, 2016

This is the last post of our Software Support and Artificial Intelligence series. You can find an overview on our introduction post. If you want to be notified when we publish more articles about AI and documentation, make sure to sign up for our mailing list.

Artificial Intelligence for documentation and support: how it could be done

AI is a game changer, and is slowly but surely transforming every possible industry. While smart automated proactive support might sound like a pipe dream on first sight, I believe that the technologies needed to make AI work for documentation are already available today.

The same type of technologies that have been developed to personalize shopping experiences can also be used to deliver personalized and contextualized... Read more

by kvantomme / 17 August, 2016

This is part 4 of our Software Support and Artificial Intelligence series. You can find an overview of the series on our introduction post. If you are reading this before all posts have been published make sure to sign up for our AI & Docs mailing list, where we send notifications when we publish these posts and similar content.

What to do when you are the tailor that makes “The Emperor's New Clothes”?



I have a confession to make: I have come to believe that most Walkthrough projects are doomed to fail. The past 4 years we’ve been working on a Walkthrough solution, so this is kind of a big deal...

Ever since we launched WalkHub , our open source Walkthrough solution, I’ve been monitoring my reactions whenever I encountered a Walkthrough on a web... Read more

by kvantomme / 11 August, 2016

This post is part 3 of our Software Support and Artificial Intelligence series. You can find an overview of the series on our introduction post. If you are reading this before all posts have been published make sure to sign up for our AI & Docs mailing list, where we send notifications when we publish these posts and similar content.

In our previous article - The Helpful co-worker model - we explained why teaching others and giving advice is very human but not always welcome. Sometimes we fail even when we try to be helpful, just like Clippy, Microsoft's artificial helpful colleague. So why did Clippy fail? Why is today different, and why should we now be able to make a programmatic helpful colleague that works?

Clippy’s story: Microsoft’s attempt to replace the... Read more
by kvantomme / 2 August, 2016

This post is part 2 of our Software Support and Artificial Intelligence series. You can find an overview of the 5 posts on our introduction post. If you are reading this before all posts have been published make sure to sign up for our AI & Docs mailing list, where we send notifications when we publish these posts and similar content.

Documentation is under pressure because of a number of trends (funding issues, shorter release schedules,...). In my last post I argued that embedded documentation could be a solution for most of these challenges. In this post I want to take a step back and look at the root interaction pattern that our support models are derived from, and see how we could use this pattern to improve our documentation systems.

Shared intentionality: a... Read more
by kvantomme / 26 July, 2016

This post is part 1 of our Software Support and Artificial Intelligence series. You can find an overview of the 5 posts on our introduction post. If you are reading this before all posts have been published make sure to sign up for our AI & Docs mailing list, where we send notifications when we publish these posts and similar content.

Documentation is important and helps software products scale

Most people will agree that documentation is a critical component for any software product. There just never seems to be enough time/money to properly document everything (we are sometimes also guilty of this). On one-off projects, you can sometimes get away with this. But when you develop a product, insufficient documentation damages your software’s scalability.

I see 4... Read more

by kvantomme / 26 July, 2016

Technical writer teams are asked the impossible: chronically understaffed, fulfill growing expectations, while dealing with the disruptions of a barrage of technological innovations.

Technology however doesn’t need to be a curse, it could be a blessing: new technologies could also be used to help technical writers. In this series I want explore how artificial intelligence and new/rediscovered interaction models for software documentation could redefine technical writing and its deliverables:

Part 1: Documentation at a crossroads
What jobs do we need documentation to fulfill? Why is documentation under pressure? Why do we need AI in documentation?

Part 2: The Helpful co-worker model
Teaching and giving advice is part of human nature. Helpful co-... Read more