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, while we involve them in all phases of our editorial workflow. The portal includes a dedicated area for conceptual information that both developers and decision makers can use when evaluating our solution. As a fully open-source, high-performance site with a Google PageSpeed Insights score of 100, it also serves as a best practice example of building your documentation site on platformOS.
The platformOS Developer Portal includes an auto-generated, always up-to-date, remote REST API reference documentation. The documentation is fully searchable and very fast, as the content is rendered on the server-side. It provides a concise and complete documentation starter kit to newcomers including conceptual information, step-by-step onboarding, and a fully working sample site with a module installed. 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. To start exploring the features of platformOS, check out the codebase, and test the endpoints of the REST API, users can set up a basic sample site of their own with a sample module added with two clicks (through our Partner Portal). We made this process extremely easy and straightforward so that users can have their own sandbox in less than a minute.
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 facilitate and encourage collaboration with our community by providing Slack support, weekly video conference, 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.