Simplify doc

Context and Problem

I want to minimize maintenance and dependency management

  • Remove features of repo that are overkill

Libraries I don’t want to maintain for now:

  • ADR libraries (used to generate architectural decision logs)
  • Storybook (it is very heavy on dependencies, forces me to include React in my project)

But I still want to document my project efficiently

Considered Options

Considered:

  • mdsvex
    • ✅ simple and flexible
    • ✅ based on Svelte
    • ❓feature complete
    • ❓can be easily used for styleguide
    • ❌ old Svelte version
  • bookit
    • ✅ based on Svelte
    • ❓feature complete
    • ❓can be easily used for more than styleguide
    • ❌ light on doc
  • Histoire
    • ✅ feature rich and flexible
    • ✅ replaces Storybook
    • ❓can be easily used for more than styleguide
    • ❓dependencies
    • ❌ based on Vue (but has project for Svelte)

Decision

➖ Removed

To simplify maintenance, I will stop using the ADR system, as it is also a bit overkill.

Removed dependencies in root package.json:

"dependencies": {
 "adr-log": "2.2.0",
 "madr": "2.1.2"
}

Removed scripts in root package.json:

"scripts": {
    "build:doc": "adr-log -d ./packages/doc/decisions",
    "build:design": "node  ./packages/design/node_modules/.bin/build.js",
    "build": "npm run build:doc",
},

Removed storybook

This was a lot dependency removals. I considered and made this decision while upgrading SvelteKit. I departed from a fresh SvelteKit lib project for the ui package, and it did not include storybook. I then felt I did not to want to add it back (see reasons at the start of this document).

➕ Kept or added

ADR templates are useful, I’m keeping them for reference and for decision docs.

These are the resources used for ADR:

🚧 Chosen option for doc: mdsvex

pnpm dlx svelte-add@latest mdsvex