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 workflow. Step-by-step tutorials for more experienced users are grouped by features (e.g. Forms), ordered by difficulty (from beginner to advanced), and they cross-reference related subsections and topics. We add examples, developer tips, and best practices where applicable. Many topics and tutorial series include full example code accessible in our public GitHub repository. All code samples are displayed with language-specific code highlighting to ease comprehension. We regularly publish articles on our blog about the implementation of specific features, workflows, or best practices.
Throughout the process of building our documentation site, we followed Content First and Design Thinking approaches, and are continuously revalidating and improving our DESIGN and user experience through an iterative approach supported by user research. We built an editorial workflow that works for all participants (internal and external writer, developer, contributor, etc.) and all stages of the process (writing, reviewing, editing). We treat our docs like code, each stage of our workflow is in git, including project management (contributors can also add tickets to report
issues or requests). We advocate for the best possible performance — our developer portal has a Google PageSpeed Insights score of 100.
We deeply care for ACCESSIBILITY right from the design phase, where 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 100 Google Lighthouse Accessibility score (and other accessibility reports).
We facilitate and encourage collaboration with our community by providing Slack support, bi-weekly video conferences, status reports, roadmaps, release notes, and a blog. 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. We provide a Contributor Guide, a Style Guide, and ready-to-use templates for all content types to make contribution easier. We are grateful that last year, 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.