Creating a Status Wiki for User Stories, ADRs, Specifications and Anything Else We Could Imagine

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:

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?

  1. Logos Has One: The Logos Wiki.
  2. It’s Open Source and We Can Self Host It: will-smith-gesturing-at-the-thing.png We 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.
  3. 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.
  4. Built For Interlinking & Referencing: A wiki allows seamless referencing between different pages.
  5. 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.
  6. Structured and Flexible: Pages can evolve naturally while still being structured logically.
  7. Long-Term Maintainability: Decisions and discussions remain easily accessible and searchable in a single, self-hosted location.
  8. Full Edit History: We can easily check previous versions of documents so we won’t lose historical decisions.
  9. …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!

1 Like

Follow-Up: Status Wiki Decision & Next Steps

After several discussions and considering different options, we’ve decided to create a GitHub-based wiki as our documentation hub. You can find it here:

:pushpin: Status Wiki

This approach keeps things lightweight, integrates well with our existing GitHub workflows, and ensures easy access and version control.

We’ll start by populating it with key documents, including User Stories, ADRs, and Specifications, and refine the structure as we go. If you have ideas for additional content or improvements, feel free to contribute!

Next Steps

  1. :white_check_mark: Assess the sentiment of the whole team - We’ve decided to move forward with a GitHub-based wiki instead of a MediaWiki installation.
  2. :wrench: Set up the GitHub Wiki - The wiki is now live at Status Wiki.
  3. :open_file_folder: Define an initial structure - Establish clear categories for User Stories, ADRs, and Specifications, make sure they are easy to navigate and reference.
  4. :rocket: Trial with basic content - Start by adding content that lacks a proper home, such as ADRs, to validate the structure and workflow.
  5. :mag: Confirm usability & address issues - Identify any friction points in navigation, contributions, or referencing external docs, and adjust as needed.
  6. :bookmark_tabs: Migrate or link existing documentation - Move relevant documentation from Notion and other platforms or establish references where migration isn’t practical.
  7. :mega: Encourage team adoption - Create contribution guidelines and ensure the process remains lightweight and accessible.

Let me know if you have any thoughts or feedback. Looking forward to building a well-structured and useful knowledge base together! :rocket:

1 Like