skyledge-docs
Share repo for markdown documents, with better version control than Notion or Shortcuts.
Folder Structure
To better organize and structure the repository, please follow this categorization scheme:
First Level: Domain
Organize documents by domain (e.g., feature area, product module, or business domain).
Second Level: Category
Within each domain folder, organize documents by category:
api/- API design documents, specifications, and endpointsuiux/- UI/UX design documents, mockups, and user flowsservices/- Service architecture, design, and implementation docs- Additional categories as needed (e.g.,
infrastructure/,database/,security/, etc.)
Example Structure
forms/ api/ YYYYMMDD-api-design/ form-api-design.md form-api-example.json uiux/ YYYYMMDD-uiux-mockups/ form-mockup-v1.png form-user-flow.mdThis structure helps maintain clarity and makes it easier to find relevant documents.
Example RFC (Request for Comments) Template
When proposing significant changes or new features, it’s essential to document the decision-making process clearly.
Here is an example template for an RFC that we could use that aims to lay everything out in a way the team can easily consume.
RFC: <Title>
Status: Draft | In Review (until YYYY-MM-DD) | Accepted | Rejected | Superseded
Owners: <eng owner>, <product owner>
Reviewers: <leads, DevOps, DS, CTO>
Decision date: (fill when accepted)
1. Problem & Goals
- What pain are we solving?
- Success criteria (business + tech): <metrics, SLAs, $, lead time, etc.>
2. Context
- Current state (brief)
- Constraints & assumptions
3. Options Considered
- Option A (pros/cons, rough effort/cost)
- Option B
- Option C
4. Proposed Decision
- Chosen option + rationale
- Scope boundaries (in/out)
5. Risks & Mitigations
- Risk → Mitigation/rollback
6. Impact
- Architecture / data / DX / cost / security
- Breaking changes (yes/no) and migration plan
7. Rollout Plan
- Phases, owners, checkpoints
- Observability: what we’ll measure
8. Alternatives & Appendix
- Links, prior ADRs, diagrams
Further Reading
- Shaping Architecture Decisions
- 6 Lessons I learned while implementing technical RFCs as a decision making tool
Preview the docs site locally
The repo builds into a searchable site with Astro Starlight. The Markdown stays where it is: Starlight reads every .md file in the repo, takes each page title from its first # Heading, and builds the sidebar from the folders, so new docs show up without frontmatter or config changes. Links between docs work as normal relative links to the .md files.
npm installnpm run dev # http://localhost:4321npm run build # static site in dist/The site config is in astro.config.mjs. How docs are found and titled is in src/content.config.ts.