Problem
We currently have good documentation for how to contribute projects to the directory,
but we are missing documentation that explains how the directory itself works.
For a new maintainer or contributor, it is not clear:
- how project data is structured and updated
- how automation (GitHub Actions / bots) fits into the workflow
- how backend, frontend, shared packages, and metadata relate to each other
- what files are safe vs dangerous to touch
This creates unnecessary friction for future maintainers and makes long-term sustainability harder.
Proposal
Add a maintenance / architecture documentation file, for example:
docs/MAINTENANCE.md
ordocs/ARCHITECTURE.md
This document would explain the internal workings of the directory, not how to submit a project.
Suggested contents
Not exhaustive, but potentially:
- High-level architecture overview
(frontend / backend / shared / docs)
- Where project metadata lives and how it is updated
- How the automated update process works (GitHub Actions, bots)
- How README tables are generated
- Local development basics (if applicable)
- Common maintenance tasks
- “If something breaks, look here first” section
Even a concise, imperfect document would be far better than none.
Why this matters
- Lowers the barrier for new maintainers
- Reduces knowledge siloing
- Improves project longevity
- Aligns well with open-source best practices
Happy to help draft or contribute to the documentation if this direction makes sense.
Problem
We currently have good documentation for how to contribute projects to the directory,
but we are missing documentation that explains how the directory itself works.
For a new maintainer or contributor, it is not clear:
This creates unnecessary friction for future maintainers and makes long-term sustainability harder.
Proposal
Add a maintenance / architecture documentation file, for example:
docs/MAINTENANCE.mdor
docs/ARCHITECTURE.mdThis document would explain the internal workings of the directory, not how to submit a project.
Suggested contents
Not exhaustive, but potentially:
(frontend / backend / shared / docs)
Even a concise, imperfect document would be far better than none.
Why this matters
Happy to help draft or contribute to the documentation if this direction makes sense.