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>
3.6 KiB
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)
- Creating new applications (
- 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
- Create README.md in repository root
- Structure documentation in user-friendly format:
- Brief introduction and purpose
- Prerequisites section
- Setup instructions
- Quick start guide
- Detailed workflow documentation
- Troubleshooting section (if needed)
- Use clear, concise language with examples
- Include command snippets that users can copy-paste
- Reference only implemented features validated against archived specs
Alternatives Considered
- Wiki or separate documentation site: Rejected - adds complexity and requires maintenance of separate system
- Documentation in CLAUDE.md only: Rejected - CLAUDE.md is for AI assistant instructions, not human users
- 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