Documentation

Code optimization 

Now that we have announced the new documentation site design and told you about the changes we did and are planning to do with its structure and content, we thought it would be helpful if we shared with you how we improved and optimized our code during the redesign process. 

Assets

• Critical CSS and the manual labor involved with it is not needed anymore. Total CSS weight is around 7KB gzipped so far, and we’re planning to optimize it in the future.
• We removed Turbolinks and JS that was required to support SPA(single page application)-like behavior. 
• We inlined the sentry loader (1KB) instead of loading JS from CDN up front (37KB). 
• Icons are SVG sprites inlined in html source, used as symbols.
• All graphics are optimized SVGs. 
• We simplified font caching (no localstorage, just browser cache). 

Content

• We simplified the code responsible for generating breadcrumbs. 
• Each category has its own layout with its own menu now.
• Modules on pages are controlled by metadata inside pages (ie. table of content, questions, sidebar, contributors, feedback). 
• We don’t use remote docs, but download JSON in the background and cache it until it becomes obsolete. 
• Auto-generated docs are now searchable (GraphQL, Liquid platformOS filters and tags).

Others

• JS is compiled to modern JS, not to ES3.
• We updated the browsers list to not support very old browsers (lighter and faster CSS, JS code)
• We changed the CSS minifier to OptimizeCSSAssetsPlugin (works better with vendor CSS than postcss-csso)
• We changed the JS minifier to TerserPlugin (supports ES6 minifying).
• We removed a couple PostCSS plugins (duplication of features).

Content production

• NEW Using the GeoJSON format for Geolocation
• UPDATED Integrating Stripe
• UPDATED Processing Payments with GraphQL Mutation
• UPDATED Modules - added more information on private/public scoping
• UPDATED platformOS Payments module Readme
• UPDATED platformOS Payments Stripe module Readme
• IN PROGRESS  Article: platformOS Site Evaluation Criteria (working title)
• IN PROGRESS Article: Building Our Documentation Site on Platform OS — Part 4: Implementation 
• PLANNED Tutorial: Creating a Form with Nested Customizations

Improvements, fixes

• FIXED The icon overlaps the text
• PLANNED Improve search results

UX

Research

Onboarding strategy: This is an ongoing research where we are gathering experiences from new pOS users and also from experienced pOS users to be able to optimise the adaptation of platformOS best practices.

Design and Development

• IN PROGRESS Notification emails after module usage: Email templates for module users about module installation, new version, and update and for module creators about module scope, new version related technical info, module purchase and module unsubscription. Related to this we modify the screens of the create and edit module screens.
• IN PROGRESS Template for module resources: A template will be provided on the create module page resources section (previously Description, Documentation, and Support)
• IN PROGRESS Edit screen for module versions: through this screen users can edit version numbers and release notes
• IN PROGRESS Report about module purchase: downloadable CSV
• PLANNED Show versions and release notes on the module detail page