[WIP] Documentation supply chain #204
Description
This ticket will hold the analysis of every (relevant) FAIR repository, in terms of:
- Who is the end user of the repository's content, and what are their needs when using documentation?
- Who is the contributor to the repository's content, and what are their needs when creating documentation?
ToC:
- fair-explorer
- fair-beta-tester
- server
- fair-plugin
- planet
- aspirecloud
- fair-forge
- tsc
- fair-beacon
- start-here
- fair-parent-theme
- aspiresync
- fair-protocol
- fair-pulse
- did-manager
- trust
- .github
- cve-labeller
- fair-policy-engine
- website-content
- fair-slack-moderation-bot
fair-explorer
Repo: https://github.com/fairpm/fair-explorer
End user
End user (primary):
- WordPress site owners/admins (and the developers who support them) who want to browse, preview, and manage WordPress plugins/themes from the FAIR ecosystem inside a WordPress site.
- Developers who want to integrate externally via the plugin’s REST API.
Their documentation needs (when using docs):
- Fast install/activation path: how to install the plugin, activate it, and get to a working state quickly.
- Required setup clarity: must know they need to create pages with slugs plugins and themes, plus how URL structure works with the optional AE_ROOT constant.
- How to customize output safely: clear guidance on the template override hierarchy (child theme → parent theme → plugin defaults) and which templates can be overridden.
- REST API usage: endpoint list, parameters, and example requests—especially the Playground blueprint generator.
- Troubleshooting playbook: common failure modes (rewrite rules, templates not loading, cart persistence, REST endpoint availability) with step-by-step checks.
WP Admin / Site Builder
A WordPress site administrator / implementer persona is the best fit for end-user documentation.
Concretely: write as if you’re guiding someone who can install/activate plugins and edit pages/permalinks, but isn’t necessarily a PHP developer.
They need docs that emphasize:
- “How do I get this working on my site?” (install, activate, required plugins/themes pages, permalinks/rewrite flush)
- “How do I use it day-to-day?” (browse/search/preview, cart, Playground demo links)
- “How do I customize without coding?” (theme template override steps, which files to copy)
- “What do I do when something breaks?” (common troubleshooting paths)
Contributor
Contributor (primary):
- Developers contributing to the plugin (WordPress/PHP engineers + front-end engineers working with SCSS/JS) who will extend features, fix bugs, and submit pull requests.
Their documentation needs (when creating docs / contributing):
- Project orientation: clear explanation of the plugin’s purpose, key features, and the mental model (notably: MVC-ish structure under includes/controller, includes/model, includes/view).
- Local dev setup: exact steps to install dependencies and build assets (Composer + npm + SCSS workflows).
- Code quality expectations: what linters/formatters are used and how to run them (composer run format, composer run lint, etc.).
- Repository structure map: where to add controllers/models/templates/assets and how template overrides are expected to work.
- Contribution workflow: forking, branching, standards expectations (WordPress coding standards), and PR submission steps.
A WordPress plugin developer contributor persona is the best fit for contributor documentation.
Concretely: write for someone comfortable with PHP/WordPress internals and front‑end build tooling, who needs to get productive in the repo quickly.
They need docs that emphasize:
- Local dev setup (PHP/Composer, Node/npm, SCSS build/watch, how to run lint/format)
- Architecture orientation (where controllers/models/views live, how templates are structured/loaded)
- Coding standards + expectations (WordPress Coding Standards, any VIP constraints if applicable, how CI/linting is enforced)
- How to add/change features safely (where to put new endpoints, templates, JS behavior; backwards compatibility considerations)
- Contribution workflow (branching, PR expectations, testing steps, what maintainers review for)
fair-beta-tester
Repo: https://github.com/fairpm/fair-beta-tester
server
Repo: https://github.com/fairpm/server
End user
Primary end users: People using the hosted site at https://fair.pm/ (i.e., the public/visitors and likely FairPM users) and internal operators relying on the deployed “server” codebase to keep that site running.
What they need from documentation (in this repo):
- Service-level clarity: What this repository powers (it is “the overarching repo for the code deployed to our hosted server”). (README.md)
- Operational expectations: High-level deployment/process notes (e.g., deployment currently done by an infrastructure team via Helm; .distignore affects deployment packaging). (README.md)
- (Implied gap): There’s little end-user-facing documentation here; the docs shown are mostly developer/operator oriented rather than “how to use fair.pm” as an end-user.
Contributor
Primary contributors:
- Developers working on the WordPress-based code deployed to fair.pm.
- Infrastructure/ops team members who deploy it (explicitly mentioned as deploying via Helm).
What they need when creating/using documentation:
- Local dev setup instructions: This repo is “pre-configured with wp-env”; contributors need steps to install dependencies and start the environment (composer install, npx @wordpress/env start). (README.md)
- Deployment workflow guidance: What triggers a deploy, who performs it (infra team), and what knobs exist for release packaging (.distignore). (README.md)
- Component/plugin-specific docs: Some included code (e.g., content/plugins/airplane-mode) carries its own README explaining purpose/behavior for local development, plus contribution encouragement (PRs welcome). (content/plugins/airplane-mode/README.md)
- (Implied gap): A repo-level CONTRIBUTING.md was not found via the tool call, so guidance on doc standards, review process, and how to add/update documentation appears limited or missing.
A Senior Maintainer / Developer Advocate (WordPress platform engineer) persona is the best fit to write contributor documentation.
Why this persona fits contributors best:
- Knows the “why” behind conventions and can document project norms (architecture, coding standards, review expectations).
- Can write accurate setup + workflow docs (local dev with wp-env, Composer, debugging, tests, linting, deployment boundaries).
- Anticipates contributor edge cases (environment drift, build/deploy gotchas, how to add plugins/themes safely).
If there's a bandwidth for a split approach, the strongest pairing is:
- Senior Maintainer writes the “how we build/run/review” sections.
- Infra/Platform Engineer adds the Helm/deploy and environment-specific operational notes (since deployment is currently infra-owned).
fair-plugin
Repo: https://github.com/fairpm/fair-plugin
End-user
End user (primary):
- WordPress site owners/admins installing “FAIR Connect” into an existing WordPress site (“installation into WordPress”, install via WP Admin, configure provider/mirrors). (README.md, readme.txt)
- Hosts / platform teams who may want to point WordPress’s “central repository” traffic at their own mirror using a constant (FAIR_DEFAULT_REPO_DOMAIN). (docs/config.md)
Their documentation needs:
- Install/uninstall steps (download release ZIP, install via wp-admin, deactivate/delete). (README.md, readme.txt)
- What the plugin changes in WordPress behavior (updates/version checks, translations, events/news, emojis, etc.) so they can assess impact. (README.md, readme.txt)
- Configuration guidance + safe defaults (explicitly “minimal changes to user workflows”; how/when to set FAIR_DEFAULT_REPO_DOMAIN, and what it affects/doesn’t affect). (docs/config.md)
- Data privacy / network behavior disclosure (which remote services are contacted and why: AspireCloud, IndexNow, php.net, jsDelivr, FAIR endpoints). (README.md, readme.txt)
A “WordPress Site Administrator / Host Operator” persona is the best fit for end-user documentation for this repo.
Why this persona fits:
- The plugin is installed and managed via the WordPress admin dashboard (install ZIP, activate/deactivate/delete), which maps to site admins.
- The only explicit configuration documented (FAIR_DEFAULT_REPO_DOMAIN) targets hosts/platform teams who manage infrastructure defaults.
How to apply it in docs:
- Write the main docs for a non-developer WP admin (task-based: install → what changes → verify → troubleshoot → uninstall).
- Add a clearly separated “For hosts / advanced configuration” section for the mirror constant and any environment-level controls.
Contributor
Contributor (primary):
- Open-source contributors to the plugin (the project “welcomes contributions from all”). (CONTRIBUTING.md)
- Working-group / governance maintainers (Technical Steering Committee + Technical Independence Working Group + FAIR Working Group) who make architectural decisions and maintain the plugin. (README.md, CONTRIBUTING.md, docs/decisions/README.md)
What they need when creating documentation:
- Contribution process requirements: licensing expectations (GPLv2+), and DCO sign-off requirement (git commit -s). (CONTRIBUTING.md)
- Local dev environment instructions to reproduce behavior and validate doc changes (wp-env workflow, npm scripts; Airplane Mode mentioned to avoid inadvertent requests). (CONTRIBUTING.md; tests/phpunit/README.md)
- Decision-recording process for documenting architecture via ADRs and consensus process (docs/decisions/README.md referencing ADR pattern + contributing rules). (docs/decisions/README.md, CONTRIBUTING.md)
- Testing guidance so documentation changes that touch behavior can be validated (PHPUnit setup/run steps, single-site vs multisite, coverage). (tests/phpunit/README.md)
A “WordPress plugin contributor (developer) working in an open-source, working-group governed project” persona is the best fit to write documentation for contributor to this repo.
Why this persona fits:
- Contributors are expected to follow OSS process requirements like GPLv2+ compatibility and DCO sign-off (git commit -s). (CONTRIBUTING.md)
- They need to run the project locally using the provided wp-env / npm workflow and understand the project’s governance/decision process (ADRs, consensus). (CONTRIBUTING.md, docs/decisions/README.md)
- They may need to validate changes with PHPUnit (single-site/multisite, coverage). (tests/phpunit/README.md)
How to apply it in docs:
- Assume the reader is comfortable with Git, PHP, npm, Docker/wp-env, and WordPress plugin internals.
- Emphasize how to set up, test, and submit changes (including how architectural changes should be documented via ADRs).
planet
Repo: https://github.com/fairpm/planet
aspirecloud
Repo: https://github.com/fairpm/aspirecloud
fair-forge
Repo: https://github.com/fairpm/fair-forge
tsc
Repo: https://github.com/fairpm/tsc
fair-beacon
Repo: https://github.com/fairpm/fair-beacon
start-here
Repo: https://github.com/fairpm/start-here
fair-parent-theme
Repo: https://github.com/fairpm/fair-parent-theme
aspiresync
Repo: https://github.com/fairpm/aspiresync
fair-protocol
Repo: https://github.com/fairpm/fair-protocol
fair-pulse
Repo: https://github.com/fairpm/fair-pulse
did-manager
Repo: https://github.com/fairpm/did-manager
trust
Repo: https://github.com/fairpm/trust
.github
Repo: https://github.com/fairpm/.github
cve-labeller
Repo: https://github.com/fairpm/cve-labeller
fair-policy-engine
Repo: https://github.com/fairpm/fair-policy-engine
website-content
Repo: https://github.com/fairpm/website-content