| name | documentation-best-practices |
| description | Laravel guidance to write meaningful documentation that explains why not what; focus on complex business logic and self-documenting code |
| tags | ["laravel","php"] |
Documentation Best Practices
Use this skill when a Laravel task involves documentation best practices.
This skill is adapted to the personal Laravel standards in this repository. It maps the public documentation-best-practices topic from jpcaparas/superpowers-laravel into the local documentation-best-practices catalog without copying third-party skill body text.
Syarif Defaults
- Follow Laravel conventions before introducing custom abstractions.
- Prefer project-local patterns when they are explicit and tested.
- Keep controllers focused on HTTP orchestration.
- Put validation, authorization, transactions, side effects, and integrations at clear boundaries.
- Keep client names, credentials, internal URLs, provider secrets, and project-specific business rules out of reusable standards.
- Verify important behavior with the smallest meaningful tests and quality checks.
Workflow
- Detect the Laravel version, PHP version, runner, package manager, and existing project conventions.
- Identify the smallest local skill set that overlaps this topic.
- Implement or review the change using Laravel-native APIs first.
- Add abstractions only when they reduce real complexity or protect a meaningful boundary.
- Run targeted tests and available quality checks before handoff.
Checkpoints
- Authorization and validation boundaries are explicit.
- Query shape, transactions, queues, cache, files, and external calls are intentional when touched.
- User-facing behavior has feature, unit, browser, or integration tests at the right level.
- Logs and errors are useful without exposing secrets or unnecessary personal data.
- Documentation or proposals avoid importing source-project names or one-off business rules.
Related Skills
using-laravel-standardsarchitecturetestingsecurity
