Documentation Improvements #35

New issue

Closed

opened 2026-02-13 18:37:49 +03:00 by NiXTheDev · 1 comment

NiXTheDev commented

2026-02-13 18:37:49 +03:00

(Migrated from github.com)

Improve and expand project documentation.

Scope

Enhance all documentation without requiring external tools or infrastructure.

Documentation to Add

Architecture Decision Records (ADRs) - why key decisions were made
Troubleshooting guide for common issues
Security best practices
Performance tuning guide
Migration guides for version updates

Documentation to Improve

README - add badges, better quickstart
CONTRIBUTING.md - expand with examples
Code comments - add more JSDoc
Environment variable reference - add validation rules
Docker deployment guide - add more examples

Generated Documentation

Add TypeDoc for API documentation generation
Generate docs from code comments
Include in CI pipeline

Organization

docs/ folder for guides
Keep README focused on quickstart
Separate advanced topics into docs/

No External Dependencies

All docs in markdown
No wiki or external documentation sites
Viewable directly in GitHub

Testing

Verify all code examples work
Check all links are valid
Review for clarity and accuracy

Improve and expand project documentation. ## Scope Enhance all documentation without requiring external tools or infrastructure. ## Documentation to Add 1. Architecture Decision Records (ADRs) - why key decisions were made 2. Troubleshooting guide for common issues 3. Security best practices 4. Performance tuning guide 5. Migration guides for version updates ## Documentation to Improve 1. README - add badges, better quickstart 2. CONTRIBUTING.md - expand with examples 3. Code comments - add more JSDoc 4. Environment variable reference - add validation rules 5. Docker deployment guide - add more examples ## Generated Documentation 1. Add TypeDoc for API documentation generation 2. Generate docs from code comments 3. Include in CI pipeline ## Organization - docs/ folder for guides - Keep README focused on quickstart - Separate advanced topics into docs/ ## No External Dependencies - All docs in markdown - No wiki or external documentation sites - Viewable directly in GitHub ## Testing - Verify all code examples work - Check all links are valid - Review for clarity and accuracy

NiXTheDev commented

2026-02-13 19:24:43 +03:00

(Migrated from github.com)

Architecture Decision Records (ADRs) - why key decisions were made

docs/ folder for guides

Not just guides, more of the general Documentation folder, can probably be moved to wiki instead

Architecture Decision Records (ADRs) - why key decisions were made

Basically FAQ for dummies

No wiki or external documentation sites

GH has per-repo wiki

Keep README focused on quickstart

rather general information, QuickStart can be delegated to the wiki

Migration guides for version updates

not needed, the db is ephemeral, it updates with the bot on every restart

CONTRIBUTING.md - expand with examples

Also stipulate more clearly that incoming PR's from others must use dev branch as base to merge into, despite release being the default, branch protection rules should also be added

Performance tuning guide

or, better yet, dynamic defaults, for ex.: max-workers would by default be the amount of cores a docker container/bun can see, but only if it's not overriden with the .env configuration, and alike

> 1. Architecture Decision Records (ADRs) - why key decisions were made > - docs/ folder for guides Not just guides, more of the general Documentation folder, can probably be moved to wiki instead > 1. Architecture Decision Records (ADRs) - why key decisions were made Basically FAQ for dummies > - No wiki or external documentation sites GH has per-repo wiki > - Keep README focused on quickstart rather general information, QuickStart can be delegated to the wiki > 5. Migration guides for version updates not needed, the db is ephemeral, it updates with the bot on every restart > 2. CONTRIBUTING.md - expand with examples Also stipulate more clearly that incoming PR's from others must use `dev` branch as base to merge into, despite `release` being the default, branch protection rules should also be added > 4. Performance tuning guide or, better yet, dynamic defaults, for ex.: max-workers would by default be the amount of cores a docker container/bun can see, but only if it's not overriden with the .env configuration, and alike