Introduction of the Portal
The platformOS Developer Portal provides onboarding, conceptual information, tutorials, examples, API references, use cases, and best practices to developers building their apps or sites on platformOS. Following the docs as code approach, it is built for iterations and collaboration — it swiftly adapts to our users’ needs as we involve them in all phases of our editorial workflow.
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 on it by only clicking through a setup wizard.
- Semi-technical users:
The Sandbox route lets you create a sandbox to experiment in by cloning a demo site from our GitHub repository. 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, that 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, main building blocks, and the logic behind platformOS, while also giving you some recommendations on the workflow.
We provide two options for users to start building their platformOS sites: start from a pre-made template or from scratch based on our detailed tutorials.
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:
Our workflow is unique in its flexibility to support any type of participant: internal developers, writers, editors, partners, or external contributors. We implemented a complete docs as code workflow on GitHub and took it even further by incorporating issue tracking and project management. We implemented continuous integrations and continuous deployment with automated testing. Our editorial workflow ensures that contribution works the same way for everyone, and we support our contributors with a Contributor Guide, a Style Guide, and Markdown templates for each type of content.
Learn more about our editorial workflow from:
- our presentation at Write The Docs 2020 — Helping Your Community Contribute to Developer Documentation https://www.youtube.com/watch?v=zm5Iw7jsyC4
- our presentation at Evolution of TC 2021 (for registered participants only) — A Complete Docs as Code Workflow, A Case Study of the platformOS Developer Portal https://evolution-of-tc.com/program/detail/a-complete-docs-as-code-workflow-a-case-study-of-the-platformos-developer-portal
We are grateful that the platformOS community's effort was acknowledged by the UK Technical Communication Award. The developer portal was recognized for many aspects including workflow, collaboration with the community, clarity and structure of the content, and information architecture of the site.