Overview

This document defines the standard for organizing developer documentation in the docs/ directory and the planning workflow for TendSocial development.

Planning Workflow

GitHub Projects-Based Planning

TendSocial uses GitHub Projects (#2) for planning and tracking work. All planning, feature specs, and task tracking happen in GitHub Issues, not in static documentation files.

Workflow:

1. Feature Planning: Create implementation plan using AI agent (/create_imp_plans)
2. Issue Creation: Post plan as issue comment, update status to "Review Imp Plan"
3. Approval: Review and approve/request changes to implementation plan
4. Execution: Move issue to "In Progress" and implement
5. Verification: Test, verify, close issue when complete

Issue Conventions:

• Use issue templates for consistency
• Link related issues with #issue-number
• Reference code with file links in comments
• Use GitHub Projects for status tracking (Backlog, Review Imp Plan, Ready, In Progress, Done)

Documentation Types

Documentation in /docs serves different audiences:

• docs/api/: Public API documentation for integration users
• docs/client/: End-user documentation for TendSocial features
• docs/developer/: Technical documentation for contributors
• docs/standards/: Project standards and conventions
• docs/implementation/: Temporary implementation specs (archive when complete)

Directory Structure

docs/
├── api/                    # API documentation
│   ├── guides/            # Integration guides (auth, OAuth)
│   └── reference/         # API endpoint reference
├── client/                 # User-facing documentation
│   ├── features/          # Feature documentation
│   └── get-started/       # Onboarding guides
├── developer/              # Developer documentation
│   ├── architecture/      # System architecture docs
│   ├── features/          # Feature implementation details
│   ├── deployment/        # Deployment guides
│   ├── archive/           # Completed/outdated docs
│   └── README.md          # Developer documentation index
├── implementation/         # Active implementation specs (temporary)
└── standards/              # Project standards

File Naming Conventions

Developer Documentation

Use descriptive kebab-case names organized by topic:

• Architecture: architecture/[topic].md (e.g., database-schema.md, tech-stack.md)
• Features: features/[feature-name].md (e.g., asset-library.md, analytics/calculation-methods.md)
• Deployment: deployment/[guide-name].md (e.g., guide.md, checklist.md)

Implementation Specs

Temporary specs for active development:

• implementation/[feature-name].md - Active implementation specifications
• Move to developer/archive/ when feature is complete

Archiving Process

When a feature is fully implemented and verified:

1. Archive Implementation Specs: Move from implementation/ to developer/archive/
2. Update Feature Docs: Create/update permanent documentation in developer/features/
3. Close GitHub Issue: Mark issue as complete in GitHub Projects
4. Update API Docs: If applicable, update API reference documentation

Archive Naming

Preserve implementation spec names when archiving for historical reference:

• implementation/v4.2_vercel-ai-gateway-integration.md → developer/archive/v4.2_vercel-ai-gateway-integration.md

Documentation Maintenance

Cross-References

• Link to GitHub issues: #123 or full URL for external docs
• Link to code: Use relative paths ../../apps/backend/src/routes/auth.ts
• Link between docs: Use relative paths ../architecture/database-schema.md

Keeping Docs Current

• Update docs alongside code changes
• Review documentation during PR reviews
• Archive outdated content rather than deleting (preserves history)
• Update examples to reflect current API/UI state

Documentation Review Checklist

• [ ] Links work and point to current code
• [ ] Examples match current implementation
• [ ] Screenshots/diagrams are up to date
• [ ] References to deprecated features removed
• [ ] GitHub issue links are accurate

Standards Documentation

Project-wide standards live in docs/standards/:

• documentation_standard.md (this file): Documentation organization
• naming-conventions.md: Code and route naming conventions
• github-workflow.md: Issue and PR workflow

Related Documentation

• GitHub Workflow - Issue creation and project management
• Naming Conventions - Code, route, and file naming
• Developer Documentation - Developer documentation index