Decide how to manage PURL documentation from the purl-spec or aboutcode.org repo

[mjherzog]

Our current setup for the (www)packageurl.org website is that we have many documentation files stored in two locations:

• purl-spec/docs
• packageurl.org/website/docs/purl-spec

At any point in time the content of each file should be the same in both locations except that the files in packageurl.org/website/docs/ contain a Docusaurus "header" section that is not present in the purl-spec/docs files. An example of this header is:

id: purl-spec-introduction
title: Introduction
sidebar_label: Introduction

In the current state, the files in purl-spec/docs are the primary files and the corresponding files in packageurl.org/website/docs/ are manually updated to match the text and add/update the header. We need to design a data structure and process to eliminate the manual steps. The primary options seem to be:

1. Keep the primary files in the purl-spec repo and design some CI/CD workflow in Docusaurus to pull the files directly from this location on demand. This would logically require adding the Docusaurus header data to the files in the purl-spec repo.
2. Move the primary files to the packageurl.org repo and maintain them there. In this case we would document their location and how to update them in the purl-spec repo.

Some key considerations:

• Many contributors are used to viewing and updating the documentation files in the purl-spec repo and there is some logic to keeping the files there (option 1) because documentation is primary content for a specification. On the other hand for option 2 we can redirect everyone there for documentation files after the website is live.
• We want to use the Docusaurus built-in "Edit this page" functionality to take you to the original documentation file (wherever it lives).
• The packageurl.org repo will have many files needed for the website that do not make sense to store in the purl-spec repo - major examples are the Software Specifications and Tools card grid and the Registered PURL Types grid. Those grids are implemented with MDX files and other JS-oriented artifacts that would be out of place in the purl-spec repo. There are many other files for the Docusaurus platform.
• The packageurl.org repo is JS/React-centric with many files to build the website. The purl-spec repo has very little actual code - primarily workflow scripts to generate documentation or indices (e.g. for PURL types)
• Whatever we decide to do for the PURL documentation will also apply to the VERS documentation and the vers-spec repo.
• The decision needs discussion/input from the PURL coumunity.