Best Ongoing Developer Experience - DevRel Awards 2022
platformOS won the Best Ongoing Developer Experience category at the DevRel Awards 2022.
Just being nominated for the DevRel shortlist is an honor, and platformOS was nominated in two categories. Then to also WIN - WOW! — Adam Broadway, CEO of platformOS
DevRel Awards 2022
The DevRel Awards 2022, presented by Orbit, is organized by Hoopy to celebrate the best of DevRel in 2020 and 2021. Selected from nominations made by the public, a jury of DevRel experts have chosen winners in nine categories.
platformOS was nominated in two categories, Best Developer Onboarding and Best Ongoing Developer Experience, and from nearly 1,000 nominations, we got shortlisted in both categories.
The top 3 shortlisted nominees in each category were:
Best Developer Onboarding
Best Ongoing Developer Experience
We were happy to receive the award for Best Ongoing Developer Experience.
Judges
The winners of the DevRel Awards 2022 were selected by an international jury of developer relations professionals:
- Adam Duvander, Everydeveloper
- April Speight, Microsoft
- Anthony Kiplimo, Africa's Talking
- Arkodyuti Saha, GitHub
- Jen Sable Lopez, OutSystems
- Mary Thengvall, Camunda
- Matthew Revell, Hoopy
- Pachi Parra, New Relic
Thank you to the organizers and the judges for providing their expertise and for the amazing effort in evaluating all the nominees in the various categories.
Why we won
While working on our developer experience, we continuously paid attention to
- who the members of our audience are
- how we can provide the most fitting onboarding experience
- how our team and community members can contribute to our documentation
- what editorial workflow and technical implementation would best fit our use cases
- how we can collect and analyze feedback through regular user experience research
- how we can meet and communicate with our community
- and how we can ensure accessibility, inclusiveness, and sustainability
We discuss these aspects in more detail below.
Audience
Our main target audience is Frontend Developers and Site Builders. Our audience combines technical people with various levels of programming skills like Experienced Developers, CTOs, Junior Developers and Site Builders, and non-technical people who come to our docs to evaluate if platformOS would be a good fit for their projects like Project Owners, Business Analysts, and Project Managers.
We are a B2B company, so most of our Partners are companies that build their solutions on platformOS. However, we also always make sure to have direct contact with a couple of our clients (e.g. Intel who we built DevMesh for) to be able to learn from their experiences with our platform and improve it in sync with the needs of the end-client.
We facilitate and encourage collaboration with our amazing community in many ways that we present in detail below.
Onboarding
The platformOS Developer Portal provides comprehensive onboarding journeys to the three main segments of our target audience:
- Non-technical users: The 1-Click install route takes you through registering on the Partner Portal to creating a demo site and installing the blog module by clicking through a setup wizard.
- Semi-technical users: The Sandbox route facilitates you cloning a demo site from our GitHub repository in a sandbox environment in which you can then experiment. Semi-technical users also have the option to go through our Hello, World! Guide. Hello, World! is the first part of our Get Started guide. It will teach you how to set up your development environment, create a simple site, make a small change on the home page, and deploy it. This is to make sure you have everything you need and everything works.
- Technical users: Build a ToDo List App is the second part of our Get Started guide. It walks you through the steps of creating a ToDo List app on platformOS from setting up your development environment to deploying and testing your finished app. It explains basic concepts, sharing what are the main building blocks and logic behind platformOS, while also giving you some recommendations on the workflow.
Try out the updated routes of our onboarding here:
Contribution
We wanted to make it very easy to get involved for all segments of our target audience, so we offer a number of ways to contribute, taking into consideration the time contributors have available, and their skill level. For some quick editing, like fixing typos or adding links, contributors can edit the content easily on the GitHub UI. For heavy editing, adding new content, or developers who prefer to use git, we provide a complete Docs as Code workflow. We thank all of our contributors by giving recognition to them on our Contributors page as well as on our GitHub repository’s README page.
- Feedback and contribution: Users can contribute immediately from the page where they discover a problem or miss something by clicking on the feedback card. They can choose from two ways: 1. adding feedback or 2. contributing via GitHub. Clicking the “Contribute to this page” link opens the topic in the GitHub editor.
- Style Guide: Our style guide contains guidelines for writing technical content (e.g. language, tone, etc.) and each content type in our documentation (e.g. tutorials, concept topics, etc.)
- Templates: Our site uses Liquid pages, but to make editing easier for contributors, we write documentation content in GitHub Flavored Markdown and use a Markdown converter to turn it into Liquid. Our templates include all non-changeable content and placeholders with explanations for the parts that are editable. Placeholders provide information on the recommended format (e.g. title) and any requirements or limitations (e.g. maximum number of characters).
- Contributor Guide: We describe ways for our community members to get involved in our contributor guide. We made the guide as short as possible (less than a page) with links to relevant content (e.g. style guide, templates).
Editorial workflow
When we started thinking about our editorial workflow we decided to come up with a process that could work for all participants, including developers in our team and our broader community, but also writers, editors, or external contributors.
Our main target audience is developers, and they are the ones who contribute most frequently to our documentation. As they already use some kind of version control system, most often git, we selected a tool that they are already familiar with, GitHub. And to make the whole workflow easy to adopt for them, we follow a Docs as Code approach. Our editorial workflow for content is very similar to how code gets reviewed and deployed. All of our code and content is on GitHub; and for transparency (and to have the same process for all participants), we process all project management tasks on GitHub’s issue tracker.
This means that community members can open tickets, discuss issues, see what we are planning and what we are currently working on, including pull requests that are in review. This has proven to be very helpful for our community members because the whole life cycle of any task is fully transparent and they can follow the whole process. Everything is collected on GitHub - for example, if we get feedback on the feedback block of our documentation site, we create a ticket on GitHub for that task.
The steps of our editorial workflow:
- Write new content in Markdown using the templates. You can use any editor that can produce Github Flavored Markdown.
- Submit the new topic as a pull request on Github.
- Review. We have a peer-review system in place for code and docs alike. Topics are reviewed by both technical reviewers (developers) and writers.
- Edit as needed. Repeat steps 3-4 until approved.
- Merge approved pull request.
- Deploy to staging, then to production.
Our documentation works with continuous integration and continuous deployment (CI/CD). On every code merge to our master branch our CI/CD of choice,Github Actions, runs quality checks to ensure that the website will remain operational after the changes are deployed.
These are the steps in our test process, in order:
- The system tests build assets and our auto-generated GraphQL documentation
- It deploys the project to the staging environment using our command line interface tool
- It runs end to end tests using CodeceptJS
- It runs Google Lighthouse on the production environment to catch possible performance regressions
If everything goes according to our standards, it would deploy to production.
Accessibility
We deeply care for accessibility. Right from the design phase, we use Figma’s Able accessibility plugin. We regularly test for accessibility with various tools and ensure that the site complies with all accessibility requirements as proven by its perfect scores in Google Lighthouse, Wave, and AChecker. Besides the technical requirements for accessibility, we think inclusive and accessible language is just as important. This is why we have added accessibility guidelines to our Style Guide and regularly review our content for inclusiveness. Learn more about our approach to accessibility in this article.
Community
We communicate with our community through the following channels:
- pOS Community site: One of our main communication channels is our community site, where you can ask, answer, upvote, and downvote questions, and get to know other members of the platformOS Community. More features coming soon!
- Slack support: One of our main communication channels is dedicated Slack channels, where community members ask questions, share ideas, and get to know our team members and each other. Based on their feedback, we see that community members find it very helpful to be able to directly communicate with us and each other: they can share what they’ve learned, plan their module development in sync with our roadmap and each other’s projects, and allocate their resources according to what’s going on in the business and the wider community. This communication seeds the documentation site with the most sought after topics.
- Video conference: We regularly have video conferences over Zoom called Town Halls, where community members and the platformOS team share news, demo features and modules, and have the opportunity to engage in real-time, face-to-face conversation. Our team and community members are distributed over different continents, so we try to accommodate participants in different time zones by rotating the time of this event so that everyone has the chance to participate. We also share the recording of each session.
Keeping community members in the loop
- Status reports: We regularly share status reports on our blog to keep our community updated on what we’ve achieved, what we are working on, and what we are planning for the near future. Our status reports also include calls for contribution and research participation, and the results and analysis of UX research. Subscribers can also choose to receive the status reports via email newsletter.
- Release notes: We share updates regarding new features, improvements, and fixes in our release notes.
- Blog: We regularly share articles about best practices and general news on our blog.
User experience research
Besides getting constant feedback from the community through the channels described above, we plan regular checkpoints in our process to facilitate testing and course-correction. During development activity we tie these checkpoints to development phases. At the end of each larger release we conduct user interviews and compile and share a short survey for community members to fill out. This helps us clarify the roadmap for the next development phase.
Learn more about our user research methods and previous and ongoing user research rounds.
Conference talks
We had the opportunity to share our experience and have inspiring conversations with fellow documentarians and members of the DevRel community at various conferences:
- tekom Europe 2022 — A Complete Docs as Code Workflow (webinar, no recording available)
- API The Docs 2021 — platformOS Developer Portal Demo and Q&A
- tcworld China 2021 — A Complete Docs as Code Workflow
- Evolution of TC 2021 — A Complete Docs as Code Workflow, A Case Study of the platformOS Developer Portal
- Write The Docs Prague 2020 — Helping Your Community Contribute to Developer Documentation
- DevRelCon Earth 2020 — Building Developer Documentation with a Fully Remote Team and Community
We are honored and grateful that our efforts have been recognized by this award. We would like to thank all members of our team and community who contributed to our developer experience by providing feedback, requests, edits, new content, or participating in user experience research.