May 16, 2018

Event report

Building API documentation and creating documentation in agile teams

Per Harbo Sørensen

At this event two highly relevant topics in software documentation were covered. That is how to build an API documentation set and how to work and create documentation in agile teams.

Event sponsor: SimCorp A/S (visit website)

Malene Krohn, Vice President of Product Development Services, welcomes the participants to Simcorp

Mattias Sander and Jon Jackson

Karen Mardahl and Kai Weber

Program

TimeEvent
13.00Registration 
13.30Welcome and latest news from tekom Danmark
Per Harbo Sørensen, Spokesperson at tekom Danmark
13.45Leveraging the Elements of API Documentation to Build Active Development Communities
Jon Jackson
Principal Technical Communicator, Milestone Systems
and
Mattias Sander
Techcomm Consultant, Sander Improvement Software AB
14.45Coffee break
15.15Making Agile Work for You!
Kai Weber
Lead Technical Writer, SimCorp
and
Karen Mardahl
Lead Technical Writer, SimCorp
16.15Coffee break
16.30Workshop: Group discussions where you can share your experience and ideas about today's topic among peers
17.10Presentation of the results of the workshop
17.30Light meal and networking
18.00End of event


ADDRESS:

SimCorp A/S
Weidekampsgade 16
2300 Copenhagen S

Find it on Google Maps

___________________________________________

Welcome and introduction

Per Harbo Sørensen
Spokesperson at tekom Danmark

LINK TO PRESENTATION

___________________________________________

Presentation 1:
Leveraging the elements of API documentation to build active development communities

Jon Jackson
Principal Technical Communicator, Milestone Systems
and
Mattias Sander
Techcomm Consultant, Sander Improvement Software AB

LINK TO PRESENTATION

Abstract

This presentation defined APIs and described the various information types that build a complete API documentation set. It showed the relationship between the information types, showed the expected level of expertise for which each information type is targeted, and showed how an entire documentation set can leverage community dialogue.

Outline: 

  • What are APIs and why are they used?
  • What are the difficulties of writing useful documentation as a developer, and why is it so hard "switching hats"?
  • What type of information is needed to use an API?
  • Getting started guides/walk-throughs, tutorials and hello worlds (audience and level of expertise)
  • Code samples (audience and level of expertise)
  • How-to guides (audience and level of expertise)
  • How to make this an active community? Online developer forum with integrated documentation set for cross reference

Bio

Jon Jackson, Principal Technical Communicator, Milestone Systems
Jon is a Principal Technical Communicator at Milestone Systems. Here, he is responsible for all of the SDK and API documentation, as well as cybersecurity and the design and implementation of the technical information portal. He as been active as a technical communicator for more than 30 years. He was an early adapter of SGML and DITA. He started out in California, making computer based training programs, and moved to the Czech Republic, where he worked for the Czech government and Masaryk University. For the past 20 years, he has been working in Denmark for an assortment of multinational companies, where he writes IT Pro and Developer documentation. He has a Master’s degree in English with a focus on Technical Writing from the California State Polytechnic University, San Luis Obispo.

Mattias Sander, Techcomm Consultant, Sander Improvement Software AB
Mattias used to work as a Senior Technical Writer in the financial services software industry. He now runs a techcomm consulting business - focused on process improvement and software automation, helping companies create cost-efficient and powerful documentation. Mattias has a background in engineering, and thrives on creating simple and pragmatic solutions to big and complex problems. He enjoys combining his technical skills with his passion for technical communication. Mattias holds a M. Sc. in industrial engineering and management from the Faculty of Engineering at Lund University and has 10 years of experience from the field of technical communication. His solid technical foundation and his strong writing and design skills allow Mattias to develop high-quality technical information which is easy to use, easy to understand, and easy to find – and even easy to create.

___________________________________________

Presentation 2:
Making Agile Work for You!

Kai Weber
Lead Technical Writer, SimCorp
and
Karen Mardahl
Lead Technical Writer, SimCorp

LINK TO PRESENTATION

Abstract

In software documentation, agile methods present a challenge to technical communicators: - What's the best way to create documentation in agile teams? - How to ensure consistent user assistance across teams? - What if a writer has to serve more than one or two teams? - And how to keep up with the "continuous improvements" that define agile? After almost 2 years with agile methods, Kai Weber reflected on lessons learned and innovations implemented for tech writers at SimCorp. The main learning points was about opportunities and challenges which agile practices present to technical writers, how writers add value to their teams, and how an empowered tech comm network is an asset to an agile development organisation.

Bio

Kai Weber, Lead Technical Writer, SimCorp
Kai Weber is Lead Technical Writer for SimCorp. With his focus on information strategies and change management, he's accompanied the agile transformation of technical writers at SimCorp - and lived to tell the tale. He contributes to tekom's activities as a member of their conference boards and as a contributor to the update of the ISO 26515 standard for agile software user assistance.

Karen Mardahl, Lead Technical Writer, SimCorp

Karen Mardahl is a Lead Technical Writer for SimCorp. Her daily focus is on how a technical communicator can get things done in an agile world. She is also active with TCUK - the Institute of Scientific and Technical Communicators (ISTC) yearly conference, the Danish UX community, and Danish Wikipedia.

 

________________________________________

Workshop

Group discussions where experience and ideas about the topic were shared among peers.

___________________________________________

You must be logged in to comment on this article.