Skip to content

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 endpoints
  • uiux/ - UI/UX design documents, mockups, and user flows
  • services/ - 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.md

This 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

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.

Terminal window
npm install
npm run dev # http://localhost:4321
npm 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.