Skip to content

Commit 930a1ba

Browse files
author
reidspencer
committed
Save session state
1 parent f924a91 commit 930a1ba

2 files changed

Lines changed: 116 additions & 80 deletions

File tree

‎CLAUDE.md‎

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -144,23 +144,31 @@ See [Domain concepts](../concepts/domain.md) for more details.
144144

145145
---
146146

147-
## Work In Progress Sections
147+
## Documentation Status
148148

149-
The following sections are marked as incomplete or need attention:
149+
As of 2026-01-21, a comprehensive 6-phase documentation improvement was
150+
completed. The following major sections are now complete:
151+
152+
### Completed Sections
153+
154+
- **Introduction**: All pages complete including `why-is-riddl-needed.md`,
155+
`what-is-riddl-based-on.md`, `what-conventions-does-riddl-use.md`
156+
- **Language Reference**: Complete with all processor types (Adaptors,
157+
Projectors, Streamlets, Connectors) and handler documentation
158+
- **Tools**: Complete documentation for `riddlc`, `riddl-idea-plugin`,
159+
and `riddl-mcp-server`
160+
- **Guides**: Complete guides for Authors, Developers, Domain Experts,
161+
and Implementors
162+
- **Concepts**: All concept pages complete with proper links and content
163+
164+
### Remaining Work
165+
166+
Lower priority items not addressed in the improvement plan:
150167

151168
| File | Issue |
152169
|------|-------|
153-
| `docs/riddl/guides/authors/index.md` | Work In Progress placeholder |
154-
| `docs/riddl/guides/developers/index.md` | Work In Progress placeholder |
155-
| `docs/riddl/introduction/why-is-riddl-needed.md` | Notes for future content TBD |
156-
| `docs/riddl/introduction/what-is-riddl-based-on.md` | TODO section incomplete |
157-
| `docs/riddl/guides/implementors/ways-to-use-riddl.md` | TBD section |
158-
| `docs/riddl/concepts/metadata.md` | Coming Soon placeholder |
159-
| `docs/riddl/concepts/conditional.md` | TBD sections |
160-
| `docs/riddl/concepts/element.md` | TBD section |
161-
| `docs/riddl/tools/riddl-idea-plugin/index.md` | TBD placeholder |
162-
| `docs/riddl/tools/riddl-mcp-server/index.md` | Empty file |
163-
| `docs/riddl/guides/domain-experts/duties.md` | Incomplete sections |
170+
| `docs/riddl/future-work/` | Roadmap items may need updates |
171+
| Type examples in language-reference | Could use more specialized type examples |
164172

165173
---
166174

‎NOTEBOOK.md‎

Lines changed: 95 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -2,96 +2,124 @@
22

33
## Current Status
44

5-
The ossum.tech documentation site is functional but several sections are
6-
incomplete. The RIDDL language documentation is the most developed area,
7-
with comprehensive coverage of concepts and a detailed language reference.
8-
Several user guides and tool documentation pages remain as placeholders.
5+
The ossum.tech documentation site has undergone a comprehensive 6-phase
6+
improvement. All major sections are now complete with accurate, well-organized
7+
content. The site is ready for review and deployment.
8+
9+
**7 commits pending push to origin/main.**
910

1011
## Work Completed (Recent)
1112

12-
- [x] Created CLAUDE.md for this repository - 2026-01-20
13-
- [x] Created NOTEBOOK.md to track pending work - 2026-01-20
14-
- [x] Audited all documentation for WIP markers - 2026-01-20
15-
- [x] Completed Author's Guide (`docs/riddl/guides/authors/index.md`) - 2026-01-20
16-
- Comprehensive guide covering workflow, AI collaboration, best practices
17-
- Includes common patterns: Command-Event, State Machine, Saga
18-
- Covers validation and iteration process
13+
### 2026-01-21: Documentation Improvement Plan Execution
1914

20-
## In Progress
15+
Completed all 6 phases of the comprehensive documentation improvement:
2116

22-
None currently.
17+
- [x] **Phase 1**: Fix critical documentation accuracy issues
18+
- Updated `statement.md` with current statement types
19+
- Fixed containment rules in language reference to match EBNF
20+
- Corrected include directive syntax
2321

24-
## Pending Documentation Tasks
22+
- [x] **Phase 2**: Add missing processor documentation
23+
- Expanded Handlers section with all `on` clause types
24+
- Added Adaptors, Projectors, Streamlets, Connectors to language reference
2525

26-
### High Priority - User Guides
26+
- [x] **Phase 3**: Complete introduction section
27+
- Rewrote `why-is-riddl-needed.md` (was TODO notes)
28+
- Completed Jacobsen Use Cases 2.0 section
2729

28-
| Task | File | Notes |
29-
|------|------|-------|
30-
| ~~Author's Guide~~ | ~~`guides/authors/index.md`~~ | **COMPLETED** 2026-01-20 |
31-
| Developer's Guide | `guides/developers/index.md` | Guide for RIDDL maintainers |
32-
| Domain Expert Duties | `guides/domain-experts/duties.md` | Several incomplete sections |
30+
- [x] **Phase 4**: Complete tools documentation
31+
- Wrote comprehensive `riddlc/index.md`
32+
- Wrote `riddl-idea-plugin/index.md` with features and troubleshooting
33+
- Wrote `riddl-mcp-server/index.md` with setup, auth, API reference
3334

34-
### Medium Priority - Concepts
35+
- [x] **Phase 5**: Complete guides
36+
- Wrote full Developers Guide with architecture and contribution info
37+
- Completed Domain Experts duties and relating-to-riddl guides
38+
- Completed Implementors ways-to-use-riddl with SBT integration
3539

36-
| Task | File | Notes |
37-
|------|------|-------|
38-
| Metadata concept | `concepts/metadata.md` | "Coming Soon" placeholder |
39-
| Conditional concept | `concepts/conditional.md` | Two TBD sections |
40-
| Element concept | `concepts/element.md` | TBD section at end |
40+
- [x] **Phase 6**: Fix concepts section issues
41+
- Fixed broken links, heading levels, typos
42+
- Completed metadata.md, conditional.md, streamlet.md, use-case.md
43+
- Fixed incorrect "Occurs In" references
4144

42-
### Medium Priority - Introduction
45+
### 2026-01-20: Initial Setup
4346

44-
| Task | File | Notes |
45-
|------|------|-------|
46-
| Why RIDDL is needed | `introduction/why-is-riddl-needed.md` | Has notes, needs prose |
47-
| What RIDDL is based on | `introduction/what-is-riddl-based-on.md` | TODO section incomplete |
47+
- [x] Created CLAUDE.md for this repository
48+
- [x] Created NOTEBOOK.md to track pending work
49+
- [x] Audited all documentation for WIP markers
50+
- [x] Completed Author's Guide (`docs/riddl/guides/authors/index.md`)
51+
- [x] Improved hierarchy diagram in `docs/riddl/concepts/index.md`
4852

49-
### Lower Priority - Tools
53+
## In Progress
54+
55+
None currently. All planned phases complete.
56+
57+
## Pending Tasks
58+
59+
### Lower Priority (Not in original plan)
5060

5161
| Task | File | Notes |
5262
|------|------|-------|
53-
| RIDDL IDEA Plugin | `tools/riddl-idea-plugin/index.md` | TBD placeholder |
54-
| RIDDL MCP Server | `tools/riddl-mcp-server/index.md` | Empty file |
55-
| Implementor Ways to Use | `guides/implementors/ways-to-use-riddl.md` | TBD section |
63+
| Type examples | `references/language-reference.md` | Add more specialized type examples |
64+
| Future work review | `future-work/` | May need updates for current roadmap |
65+
| Verify link integrity | All files | Run `mkdocs build --strict` |
5666

5767
## Design Decisions Log
5868

59-
| Decision | Rationale | Alternatives Considered | Date |
60-
|----------|-----------|-------------------------|------|
61-
| Use MkDocs Material | Industry standard, good search, responsive | Hugo, Docusaurus | Pre-existing |
62-
| Separate guides by role | Different audiences need different focus | Single comprehensive guide | Pre-existing |
63-
| AI context files in refs | Language ref designed for AI consumption | Inline AI hints | Pre-existing |
69+
| Decision | Rationale | Date |
70+
|----------|-----------|------|
71+
| 6-phase approach | Systematic improvement with commits after each phase | 2026-01-21 |
72+
| Statement rewrite | Old statement.md listed obsolete types from removed features | 2026-01-21 |
73+
| Processor docs in lang-ref | Language reference is authoritative; concepts link to it | 2026-01-21 |
74+
| Domain expert focus | Guides written for non-programmers working with AI | 2026-01-21 |
6475

6576
## Next Steps
6677

67-
1. Complete the Author's Guide (in progress)
68-
2. Fill in Domain Expert Duties sections
69-
3. Document the RIDDL MCP Server
70-
4. Complete the Developer's Guide
71-
5. Fill in TBD sections in concepts
78+
1. Push 7 commits to origin/main
79+
2. Run `mkdocs build --strict` to verify all links
80+
3. Deploy to production with `mkdocs gh-deploy`
81+
4. Consider adding Quick Start tutorial (optional)
82+
83+
## Files Modified in This Session
84+
85+
### Introduction
86+
- `docs/riddl/introduction/why-is-riddl-needed.md` (rewritten)
87+
- `docs/riddl/introduction/what-is-riddl-based-on.md` (completed)
88+
- `docs/riddl/introduction/what-conventions-does-riddl-use.md` (fixed)
89+
90+
### Language Reference
91+
- `docs/riddl/references/language-reference.md` (expanded significantly)
92+
93+
### Tools
94+
- `docs/riddl/tools/index.md` (fixed)
95+
- `docs/riddl/tools/riddlc/index.md` (written)
96+
- `docs/riddl/tools/riddl-idea-plugin/index.md` (written)
97+
- `docs/riddl/tools/riddl-mcp-server/index.md` (written)
98+
99+
### Guides
100+
- `docs/riddl/guides/developers/index.md` (written)
101+
- `docs/riddl/guides/domain-experts/duties.md` (completed)
102+
- `docs/riddl/guides/domain-experts/relating-to-riddl.md` (completed)
103+
- `docs/riddl/guides/implementors/ways-to-use-riddl.md` (completed)
104+
105+
### Concepts
106+
- `docs/riddl/concepts/statement.md` (rewritten)
107+
- `docs/riddl/concepts/epic.md` (fixed)
108+
- `docs/riddl/concepts/case.md` (fixed)
109+
- `docs/riddl/concepts/field.md` (fixed)
110+
- `docs/riddl/concepts/processor.md` (fixed)
111+
- `docs/riddl/concepts/handler.md` (completed)
112+
- `docs/riddl/concepts/context.md` (completed)
113+
- `docs/riddl/concepts/outlet.md` (fixed)
114+
- `docs/riddl/concepts/value.md` (completed)
115+
- `docs/riddl/concepts/sagastep.md` (fixed)
116+
- `docs/riddl/concepts/element.md` (completed)
117+
- `docs/riddl/concepts/metadata.md` (written)
118+
- `docs/riddl/concepts/conditional.md` (completed)
119+
- `docs/riddl/concepts/streamlet.md` (written)
120+
- `docs/riddl/concepts/use-case.md` (expanded)
72121

73122
## Open Questions
74123

75-
- Should the Author's Guide assume AI assistance is always available?
76-
- What level of RIDDL syntax detail belongs in guides vs. references?
77124
- Should there be a quick-start tutorial separate from the guides?
78-
79-
## Content Strategy Notes
80-
81-
### Author's Guide Direction
82-
83-
The Author's Guide should focus on:
84-
1. **Workflow**: How to approach domain modeling with RIDDL
85-
2. **AI Collaboration**: Using the Ossum MCP Service effectively
86-
3. **Best Practices**: Naming conventions, organization, documentation
87-
4. **Common Patterns**: Typical entity, handler, saga structures
88-
5. **Validation**: Using riddlc to check models
89-
6. **Iteration**: Refining models based on feedback
90-
91-
### Target Reader Profile
92-
93-
- Domain expert with business knowledge
94-
- May not be a programmer
95-
- Will use AI assistance for syntax details
96-
- Needs to understand DDD concepts
97-
- Focus on "what to model" not "how to code"
125+
- Are there additional processor types that need documentation?

0 commit comments

Comments
 (0)