Building Developer Documentation with a Fully Remote Team and Community — DevRelCon Earth 2020

Diana Lakatos | August 23, 2020

Building Developer Documentation with a Fully Remote Team and Community — DevRelCon Earth 2020

How to build developer documentation in a fully remote team for a community scattered all over the globe? In our session at DevRelCon Earth 2020, we showed the steps and iterations in our journey of building the platformOS developer portal, and talked about the approaches, processes, and tools we used from the discovery phase that led to the platformOS team winning the UKTC Award.




Process 

Information Architecture

  • How we started
  • How we got to know our audience
  • How we figured out what content we need
  • How we outlined a sitemap for our documentation site

Approaches discussed: Design Thinking, personas, remote UX workshops, card sorting, remote usability testing

Tools discussed: content inventory, sitemap, online research tools, Mural, Miro, Figma, lookback, playbookUX, UsabilityHub, OptimalWorkshop, SurveyMonkey, HotJar 

Layouts, navigation, and design

  • How we created the layouts and navigation for the site
  • How we created and iteratively updated the design based on community input

Approaches discussed: iterative design, branding 

Tools discussed: wireframes, Sketch, Figma

Content production

  • How content production started
  • How we developed and adjusted our editorial workflow
  • How we ensure continuous production of updates and new content

Approaches discussed: Content First, open source, community contributions, editorial workflow for distributed communities  

Tools discussed: style guide, templates, Markdown, GitHub

Implementation

  • Technologies we used
  • How we use GitHub for our docs as code workflow

Approaches discussed: docs as code, auto-generated documentation, automated tests, extreme performance

Tools discussed: GitHub, performance tests

Community

  • How we collaborate with our remote and distributed community
  • Channels we use to communicate
  • How we help and encourage contribution to our documentation

Approaches discussed: community-driven documentation, contributor experience, user research, feedback, asynchronous communication 

Tools discussed: contributor guide, status reports, release notes, roadmap,  blog, real-time chat, video conferencing