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 rto 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 dependecy renmovals. I actually considered and made this decision while upgrading to the RC version of 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:

Markdown Any Decision Records
arc42 template
HTML Sanity Checker Architecturehtml#section-introduction-and-goals)
biking2, Architecture and API
Architecture decision record

🚧 Chosen option for doc: mdsvex

Used mdsvex svelte adder which went smoothly using this command for pnpm:

pnpm dlx svelte-add@latest mdsvex

It wasn’t very clear how to load markdown files dynamically - this post helped : Build a static site with SvelteKit#Two ways to load Markdown