Purism’s documentation has come a long way in the past couple of years and will only continue to become a comprehensive knowledge base for Purism products and services.
As part of an effort to consolidate documentation sources and increase traceability and public accountability of Purism policies, I plan to migrate all of the published policies to our public documentation within the About section (e.g. About/Policy). The existing policies page will then redirect to the new location.
Benefits of this change
- Improved documentation consolidation, increasing visibility and SEO
- Significantly improved version control through
gitinstead of WordPress revision history- WordPress page revision history is private.
- Revision history is in HTML where relatively small material changes result in many lines modified.
- The documentation source repository is public and is readable by anyone.
- Anyone can create issues and merge requests.
- GitLab facilitates open discussion about proposed changes.
- Fewer publication steps
- WordPress static website generation must be manually activated, so there are times where a page update is not quickly reflected on the website itself.
- To the contrary, once approved by Purism staff, policy is merged into the primary branch and a CI job is automatically queued. When the build succeeds without error, the website is published with the new updates.
Future improvement opportunity
It is debatable whether docs.puri.sm has an equally professional appearance as the primary puri.sm theme in its current state, but the quality can be standardized over time through theming efforts.