Markus GrafandClaude
d39be42e81
Create OpenSpec proposal to add comprehensive user-facing documentation that explains setup, configuration, and usage of implemented features. The proposal includes: - Framework introduction and feature overview - Prerequisites and setup instructions - Complete workflow documentation (all 7 slash commands) - Quick start guide for experienced users - Directory structure explanation - Profile setup shortcut (using Claude to help populate from docs) Focuses only on implemented features, excludes aspirational/unimplemented functionality like automated CV generation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
99 lines
3.6 KiB
Markdown
99 lines
3.6 KiB
Markdown
# Proposal: Add User Documentation (README.md)
|
|
|
|
**Change ID**: `add-readme`
|
|
**Date**: 2025-11-10
|
|
**Status**: Draft
|
|
|
|
## Overview
|
|
|
|
Add a comprehensive README.md to the repository root that documents the actual working functionality of the Job Application Framework (Bewerbungszauberer). The documentation will focus on practical setup and usage instructions based on implemented features.
|
|
|
|
## Motivation
|
|
|
|
Currently, the framework lacks user-facing documentation that explains how to:
|
|
- Install and set up the framework
|
|
- Configure the profile.md file
|
|
- Use the slash commands workflow
|
|
- Generate application documents
|
|
|
|
Users need clear, step-by-step instructions that document only what is actually implemented and working, not aspirational features. This documentation will lower the barrier to entry and help new users get started quickly.
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
- Installation and setup instructions (Claude Code installation, copying src directory)
|
|
- Profile configuration guidance (including shortcut using Claude to help fill it out)
|
|
- Complete workflow documentation based on archived specs:
|
|
- Creating new applications (`/new-application`)
|
|
- Populating applications (`/populate-application`)
|
|
- Validating applications (`/validate-application`)
|
|
- Generating cover letters (`/write-cover-letter`)
|
|
- Converting to PDF (`/convert-cover-letter`)
|
|
- Generating application emails (`/write-application-email`)
|
|
- Brief framework description and purpose
|
|
- Prerequisites (system requirements)
|
|
|
|
### Out of Scope
|
|
- Unimplemented features (CV generation workflow automation)
|
|
- Development/contribution guidelines
|
|
- Internal architecture documentation
|
|
- API documentation for extending the framework
|
|
|
|
## User Impact
|
|
|
|
**Positive**:
|
|
- New users can quickly understand what the framework does and how to use it
|
|
- Clear setup instructions reduce friction in getting started
|
|
- Workflow documentation helps users leverage all implemented features
|
|
- Self-service documentation reduces need for direct support
|
|
|
|
**Neutral**:
|
|
- Existing users who already understand the workflow won't need this documentation
|
|
|
|
## Implementation Approach
|
|
|
|
1. Create README.md in repository root
|
|
2. Structure documentation in user-friendly format:
|
|
- Brief introduction and purpose
|
|
- Prerequisites section
|
|
- Setup instructions
|
|
- Quick start guide
|
|
- Detailed workflow documentation
|
|
- Troubleshooting section (if needed)
|
|
3. Use clear, concise language with examples
|
|
4. Include command snippets that users can copy-paste
|
|
5. Reference only implemented features validated against archived specs
|
|
|
|
## Alternatives Considered
|
|
|
|
1. **Wiki or separate documentation site**: Rejected - adds complexity and requires maintenance of separate system
|
|
2. **Documentation in CLAUDE.md only**: Rejected - CLAUDE.md is for AI assistant instructions, not human users
|
|
3. **Video tutorial**: Rejected - text documentation is easier to maintain and update
|
|
|
|
## Success Criteria
|
|
|
|
- [ ] README.md exists in repository root
|
|
- [ ] Documentation covers all implemented slash commands
|
|
- [ ] Setup instructions are clear and actionable
|
|
- [ ] No references to unimplemented features
|
|
- [ ] Uses examples from actual usage patterns
|
|
- [ ] New users can follow README to complete a full application workflow
|
|
|
|
## Dependencies
|
|
|
|
None - documentation change only.
|
|
|
|
## Risks
|
|
|
|
**Low Risk**: This is purely additive documentation. No code changes required.
|
|
|
|
**Mitigation**: Review against actual implementation to ensure accuracy.
|
|
|
|
## Related Changes
|
|
|
|
None - standalone documentation addition.
|
|
|
|
## Specs Modified
|
|
|
|
- **NEW**: `user-documentation` - Documents the requirements for user-facing README
|