platformOS Developer Portal (2022)

Introduction

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 the Platform-as-a-Service (PaaS) framework that is platformOS. Following the docs as code approach, it is built to accommodate constant iteration and collaboration — with our developer community being involved in all phases of our editorial workflow, the portal is quick to adapt to their ever evolving needs. 

Why nominated?

BEST ACCESSIBLE DEVPORTAL

We deeply care about accessibility. We address accessibility right from the design phase, where we use Figma’s Able accessibility plugin. We follow the rules for foreground and background color contrast, font size, and graphical objects (like icons, form fields, etc.), to ensure that our site conforms with WCAG AAA. 

As another foundation for accessibility, we make sure to only use (and correctly use) semantic HTML — this helps assistive technologies (like screen readers) convey information to their users by following the semantic structure. In addition to ensuring a consistent structure, semantic HTML facilitates web browsers applying default accessibility features for specific HTML elements. For example, buttons allow for keyboard accessibility (can be navigated to and clicked using the keyboard). 

We regularly test for accessibility with various tools. Recent test results of the platformOS Developer Portal:

• Lighthouse: Accessibility score 100/100
• WAVE web accessibility evaluation tool - no errors 
• AChecker (Web Accessibility Checker): WCAG 2.0 (Level AAA) - no known problems

As semantic HTML is essential for accessibility, we make sure not to style text any other way than through Markdown, which is then translated into HTML. We provide ready-to-use templates for all content types that include all non-changeable content and placeholders with explanations for the sections that are to be contributed by users.

The aspects described above provide a solid technical foundation. But to optimize for accessibility, content needs to be curated with accessibility in mind. To help the community in this regard, we provide the following guidelines in our Documentation Style Guide.

Guidelines for structuring content 

• Using headers for structuring content: The Markdown format we use is translated into semantic HTML to help screen readers navigate through our content. We use headers as described in the style guide and follow the templates provided to ensure consistency. We never skip a header level for styling reasons.
• Improving readability by using concise language, writing short paragraphs, and using lists where possible.
• Using alternative text for images and icons, keeping in mind that screen readers read this text out loud.
• If the image serves a function as part of the documentation, we describe the image in detail. Users receive the same information from the alt text that they would receive when viewing the image. 
• Including the data for charts or graphs in the alt text.
• When using screenshots to show what the user has to do, the alt text doesn’t repeat the information already described in text.
• Decorative images don't have alt text — it would only be a distraction.
• When inserting an image, we pay attention to the contrast ratio, image quality, and its size in kilobytes. The smaller the image, the more accessible it is. Many people around the world still have poor internet connectivity. 
• Providing information as text when using videos - not everyone can interpret video content efficiently. 

Guidelines for accessible language

We write so that the language we use is inclusive and global, and reflects our users’ diversity (including, for example, race, gender, ability, location, etc.).

• Definitions for all terminology: We introduce new concepts by starting with a definition, and adding them to the Glossary. We explain acronyms when first used.
• Technical language: We use the most specific word we can to talk about technical concepts and processes. For example, we don't say "take" when we mean "copy", or don't say "put" when we mean "install".
• Gender-neutral pronouns: We don’t use gender-specific, third-person pronouns such as he, she, his, and hers. We use the second person when possible, and "they" when needed.
• Descriptive link text: To help keyboard navigation, we add the information into the link text. For example, instead of writing "learn more" or "click here", we write the topic title.
• Avoiding ableist language: We don't use words that assume an ability the user might not have (for example, "as you can see" implies the user has a capacity for vision). We avoid directional language, for example, "blue button" or "button below the headline".
• Never perpetuating racism, bias, and harm: We replace terms like "blacklist" and "whitelist" with terms like "allowed" or "blocked", or replace "native" with "built-in". 
• We avoid metaphors and colloquialisms.

BEST DEVPORTAL BEYOND REST PLATFORMS

GraphQL is a domain-specific language that we have baked into the core of platformOS along with Liquid markup, both of which are open-source frameworks. We have clear documentation for both, not just the open-source documentation that we synchronize with, but additional support and examples that have really helped our ecosystem of developers get up to speed. We facilitate  developers, who wish to learn best practice, to transition from older frameworks to experiencing the power and flexibility of GraphQL, especially when combined with the “APIs-for-Everything” devops-in-box ecosystem offered by platformOS.

Onboarding

To date, we have developed three main onboarding journeys for the three main segments of our target audience.

• Non-technical users can go through the 1-click route that takes them through registering on the Partner Portal and then, by clicking through an intuitive and simple setup wizard, have them create a demo site and install the blog module in just minutes.
• Semi-technical users can create a sandbox in which they can experiment by cloning a demo site from our GitHub repository. They also have the option to go through our Hello, World! Guide.
• Technical users can follow a more complex tutorial that walks them through the steps of creating an app on platformOS, such as setting up their development environment, syncing with github, deploying and testing their apps, and more. It explains basic concepts, including giving insights into the main building blocks and the logic behind platformOS, while also giving recommendations on best practice workflows.

Separately, we provide two routes for developers to start building a platformOS site instance: start from a premade multi-sided marketplace template, or from scratch (supported by our detailed tutorials). The premade marketplace template is a fully functional marketplace built on platformOS with features such as user onboarding, ad listings and ads, in-app messaging, purchase and checkout, online payment processing, splitting of payments, and more. Following our tutorial, the developer can deploy the template code within minutes giving a broad range of working features that they can then start customizing (both the back- and front-end code), with no limits.

Developer Guide

Our Developer Guide provides detailed descriptions of concepts, step-by-step tutorials, references, and examples for implementing various features on platformOS. It starts with an overview of what platformOS is, and then includes in depth topics covering the recommended development workflow, explaining directories and files in the codebase and how to use our command line tool, and getting developers acquainted with our support. These topics help developers create a mental model of our platform, and lay the foundations for confidently using platformOS. 

Topics are grouped by features (e.g. Forms), ordered by difficulty (from beginner to advanced), and are cross-referenced to related subsections and topics. Sections usually start with the description of the concept and related background information, then offer one or more tutorials for beginners, and more complex tutorials for advanced users. This makes sure that developers can find all information related to a feature in one place. All topics include code examples, developer tips, and best practice guides where applicable.

Best Practices

In the Best Practices section, we collect articles and tutorials from experienced platformOS developers across a wide variety of topics, including code quality, development workflow, performance, testing and QA.

Although topics in this section are primarily aimed at experienced developers who might want to fine-tune various aspects of their process, beginners can also benefit from reading the articles, helping them form a better understanding of the underlying concepts behind platformOS and starting to implement on the PaaS with a best practice approach.

Use Cases

Use cases describe in detail how we implemented a feature, a module or a web application in platformOS. They describe the problem, the challenges and solutions, and always provide insight into our decision-making process: Why did we decide on one technical approach over another? What factors did we consider? What are the current industry best practices?

Use cases include links to related documentation topics, resources related to the topic (e.g. articles), all assets we used (e.g. templates), example code in our GitHub repository and live demos.

BEST NEW DX INNOVATION 

We strive to continuously pay attention to all aspects that impact the developer experience on the platformOS developer portal, such as:

• Understanding our target audience
• How to provide the most fitting onboarding experience for different target audience segments
• How to empower our team and community members to contribute to our documentation
• What editorial workflow and technical implementation would best suit various use cases
• How to collect and analyze feedback through regular user experience research 
• How to meet and communicate with our community
• How to ensure accessibility, inclusiveness, and sustainability

We are grateful that our developer experience has won the Best Ongoing Developer Experience award at the DevRel Awards 2022. 

User Experience

• Audience: Our main target audience is front-end developers and business owners/site builders. Our audience combines technical people with various levels of programming skills - like experienced developers, CTOs, junior developers, as well as non-technical people who come to our docs to evaluate if platformOS might be a good fit for their projects - like project owners, business analysts, and project managers. 
• Onboarding: The platformOS Developer Portal provides comprehensive onboarding journeys to the three main segments of our target audience, and two options for developers to start building their platformOS sites; start from a premade template or from scratch using our detailed tutorials. Our onboarding has been recognized by the Best Onboarding award at the DevPortal Awards 2021. 
• Contribution: To make it very easy for all segments of our target audience to be involved, we offer a number of ways to contribute, taking into consideration the time contributors have, 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. We provide a Contributor Guide, Style Guide, and templates for different content types.
• Editorial workflow: We provide a complete docs as code editorial workflow and our documentation works with continuous integration and continuous deployment (CI/CD). On every code merge to our main branch our CI/CD of choice, Github Actions, runs quality checks to ensure that the website will remain operational after the changes are deployed. We are excited that our editorial workflow has won the Best Editorial Experience award at the DevPortal Awards 2021. 
• Accessibility: We plan for accessibility from the outset during the initial design phase, and regularly test for accessibility with various tools - further validated by our Documentation site’s very high to often 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.
• Community: We communicate with our amazing community through many different channels such as our community site, Slack support, and regular video conferences. We keep our community members in the loop by regularly sharing status reports outlining 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. We share updates regarding new features, improvements, and fixes in our release notes, and 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.

Sustainability

Based on total ICT emissions compared with carbon emission by country, if the Internet was a country, it would be the 7th largest polluter. What’s even more alarming is that the electricity consumption and carbon emissions from our digital lives is on a sharp increase. This is why we want to emphasize the importance of sustainability when building websites. 

Some of the factors we pay attention to in order to make our developer portal sustainable:

• Green hosting 
• Performance
• Image management
• Video management 
• Fonts 
• Web caching 
• User experience
• Navigation, search
• Content management
• Search engine optimization
• Third-party tools
• Maintenance 

Many of the best practices we follow are just as beneficial for the people as the planet, for example, achieving the best possible performance or providing the best user experience tailored to the needs of our audience. 

Based on the Website Carbon Calculator, our developer portal runs on sustainable energy and is cleaner than 95% of websites tested. On Ecograder, the platformOS Developer Portal scores 100 out of a possible 100 points.  

We believe it’s imperative to decrease the carbon footprint of our digital lives. As platformOS facilitates building apps and websites, we would like to lead by example and show how a developer portal can be sustainable without ever compromising on user experience.