Background
Currently, our documentation is spread across multiple platforms. To help us navigate into a requirements first development cycle we should consider how and where we record our requirements and decisions in a manner congruent with our organisational principles:
- User Stories: Stored in Notion, making it difficult to track references between closed and open discussions.
- ADRs (Architecture Decision Records): We do not have a structured place for these, and we don’t really even make these it would be a great place to start in an open space. For more details please see GitHub - joelparkerhenderson/architecture-decision-record: Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation
- Specifications: Managed in GitHub, which works well but lacks a simple way to interlink with other documents.
- Other Things: We store all kinds of information in various different places and it is really hard to track it all down or cross reference it. See here for a few examples
This fragmentation makes it difficult to maintain a cohesive record of our decisions, references, and discussions.
Proposal
We propose setting up a MediaWiki wiki as a self-hosted repository for:
- User Stories: Easily linked across pages, with open and closed stories documented in a structured format.
- ADRs: A clear record of architectural decisions, allowing for easy referencing and discussion.
- Specifications: While still maintained in GitHub, references and summaries can be linked from the wiki.
- Other Things: See here for a few examples
Why a Wiki?
- Logos Has One: The Logos Wiki.
- It’s Open Source and We Can Self Host It:
will-smith-gesturing-at-the-thing.pngWe talk a lot about not wanting to be tied to a centralised 3rd party document service like Notion, but we don’t take action to remedy it. - Easy to Edit: GitHub is great for version control, but using Git for documentation and decision updates can be overkill. A wiki provides a lightweight, intuitive way to edit and update documentation.
- Built For Interlinking & Referencing: A wiki allows seamless referencing between different pages.
- Designed For Open Collaboration: A wiki encourages contributions from the whole team without requiring them to have special permissions, need to learn Git workflows, have special technical knowledge.
- Structured and Flexible: Pages can evolve naturally while still being structured logically.
- Long-Term Maintainability: Decisions and discussions remain easily accessible and searchable in a single, self-hosted location.
- Full Edit History: We can easily check previous versions of documents so we won’t lose historical decisions.
- …It’s Open Source and We Can Self Host It:
shia-labeouf-just-do-it.gif
Other Things We Could Maintain in the Wiki
Besides User Stories, ADRs, and Specifications, we could also use the wiki for:
- Team Agreements & Policies:
- E.g., coding guidelines, review processes, decision-making principles, records of procedure, agreements and rationales.
- Tooling & Infrastructure Documentation:
- Explanations of internal tools, CI/CD pipelines, and development environments.
- Best Practices:
- Lessons learned, templates, and guidelines for various workflows.
- Onboarding Documentation:
- Guides for new team members to get up to speed quickly.
- Technical Research & RFCs:
- A place to document research findings, alternatives explored, and future technical considerations.
- Glossary of Terms:
- Definitions of commonly used concepts, acronyms, and team-specific terminology.
Next Steps
1. [] Assess the sentiment of the whole team, if we agree proceed with next steps. If not, understand and record the reasons, try to come to a compromise, if all else fails pursue an alternative.
2. [] Set up a Wikimedia installation for internal use.
3. [] Define an initial structure (e.g., categories for User Stories, ADRs, and Specs).
4. [] Trial with basic things that don’t have a properly defined home like ADRs and User Stories.
5. [] Confirm it all works as expected, identify and address any pain points or friction.
6. [] Migrate existing documentation to the wiki in phases. Or commit to phase out the usage of other sources.
7. [] Encourage team adoption with documentation guidelines and lightweight contribution processes.
Superseded by a github wiki implementation
We would love to hear the team’s thoughts on this!
Assess the sentiment of the whole team - We’ve decided to move forward with a GitHub-based wiki instead of a MediaWiki installation.
Set up the GitHub Wiki - The wiki is now live at 
Define an initial structure - Establish clear categories for User Stories, ADRs, and Specifications, make sure they are easy to navigate and reference.
Trial with basic content - Start by adding content that lacks a proper home, such as ADRs, to validate the structure and workflow.
Confirm usability & address issues - Identify any friction points in navigation, contributions, or referencing external docs, and adjust as needed.
Migrate or link existing documentation - Move relevant documentation from Notion and other platforms or establish references where migration isn’t practical.
Encourage team adoption - Create contribution guidelines and ensure the process remains lightweight and accessible.