laantungir/ngit-grasp

Fork 0

mirror of https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git synced 2026-10-05 15:08:24 +00:00

Files

T

History

DanConwayDev 8c129a4aea docs: add guidance to keep architecture docs updated

- Added CRITICAL warning section to AGENTS.md about treating architecture
  docs as living documents
- Mark 'Keep Architecture Docs Updated' item as fixed in grasp-01 learnings
- Mark 'Document actual architecture' technical debt item as fixed

This addresses a key learning from GRASP-01 where docs described plans
rather than implementation, causing confusion.

2025-12-04 15:45:48 +00:00

grasp-01-implementation.md

docs: add guidance to keep architecture docs updated

2025-12-04 15:45:48 +00:00

grasp-audit.md

docs: update based on current implementation

2025-12-04 13:02:59 +00:00

nix-flakes.md

docs: major cleanup and reorganization

2025-11-04 09:31:57 +00:00

nostr-sdk.md

docs: major cleanup and reorganization

2025-11-04 09:31:57 +00:00

README.md

docs: use Diátaxis structure

2025-11-04 10:25:53 +00:00

README.md

Learnings Directory - DEPRECATED

Status: This directory is deprecated as of November 4, 2025.

What Happened?

We migrated to the Diátaxis documentation framework, which provides a clearer structure based on content purpose rather than origin.

Where Did Content Go?

The "learnings" were distributed into appropriate Diátaxis categories:

Gotchas and Patterns → How-To Guides

nix-flakes.md → docs/how-to/nix-flakes.md
Task-oriented solutions to common problems

Technical Details → Reference

nostr-sdk.md → docs/reference/nostr-sdk-upgrade.md (planned)
git-http-backend.md → docs/reference/git-protocol.md
Factual technical information

Concepts and Understanding → Explanation

grasp-audit.md → Incorporated into docs/explanation/architecture.md
Discussion of design and architecture

Why the Change?

The "learnings" category was ambiguous:

Mixed gotchas, patterns, and concepts
Unclear where to put new content
Hard for readers to know what to expect

Diátaxis provides clear categories:

Tutorials - Learning by doing
How-To - Solving problems
Reference - Looking up facts
Explanation - Understanding concepts

See docs/README.md for the new structure.

For Content Authors

Don't create new files here. Instead, ask:

"Can you teach me to...?" → docs/tutorials/
"How do I...?" → docs/how-to/
"What is...?" → docs/reference/
"Why...?" → docs/explanation/

Migration Status

✅ nix-flakes.md → Migrated to how-to/nix-flakes.md
⏳ nostr-sdk.md → Being incorporated into reference docs
✅ grasp-audit.md → Content in explanation/architecture.md

This directory will be removed in a future cleanup.
See AGENTS.md for documentation guidelines.