Building Developer Documentation with a Fully Remote Team and Community — DevRelCon Earth 2020
Diana Lakatos | August 23, 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