Dog Laravel Package

Product Decisions This Supports

• Automated Documentation Generation: Reduces manual effort in maintaining API documentation for PHP/Laravel projects by auto-generating Markdown-based docs from source code and PHPDoc.
• Developer Experience (DX) Improvements: Enables self-documenting code by enforcing PHPDoc standards (aligned with PSR-19) and surfacing issues early via configurable validation rules.
• Roadmap for Open-Source Contributions: Justifies investment in documentation tooling for public-facing Laravel packages, reducing friction for contributors.
• Build vs. Buy: Avoids reinventing documentation tools (e.g., custom scripts or paid solutions like phpDocumentor) by leveraging a lightweight, extensible open-source alternative.
• Use Cases:
  • Public APIs: Generate API references for Laravel packages (e.g., laravel/framework).
  • Internal Libraries: Enforce documentation standards across microservices or monoliths.
  • Onboarding: Provide auto-generated docs for new developers (integrates with MkDocs/Material for polished output).
  • CI/CD Pipelines: Fail builds on critical doc issues (e.g., missing @param types) via --analyze mode.

When to Consider This Package

• Adopt if:

  • Your PHP/Laravel project lacks consistent, up-to-date documentation.
  • You need PHPDoc validation (e.g., enforce @param types, @return tags) without manual reviews.
  • Your team uses Markdown (e.g., for GitHub READMEs, MkDocs, or Docusaurus).
  • You want low-maintenance docs that auto-update with code changes.
  • Your project aligns with PSR-19 (proposed PHPDoc standards).

• Look Elsewhere if:

  • You need HTML/PDF output (use phpDocumentor or Doxygen).
  • Your codebase is non-PHP (e.g., JavaScript, Python).
  • You require advanced features like UML diagrams (use PlantUML or phpDocumentor plugins).
  • Your team prefers interactive docs (e.g., Swagger/OpenAPI; use zircote/swagger-php).
  • You need enterprise support (consider commercial tools like Dash or Zephyr).
  • Your project is PHP < 8.0 (Dog requires PHP 8.0+).

How to Pitch It (Stakeholders)

For Executives:

*"Dog is a lightweight, automated tool to generate and enforce high-quality documentation for our PHP/Laravel projects. By integrating this into our workflow, we can:

• Reduce onboarding time for new engineers with self-updating API references.
• Improve code quality by catching PHPDoc issues early (e.g., missing @param types).
• Cut documentation maintenance costs by 50%+—docs auto-generate from code.
• Align with open-source best practices (PSR-19 compliance) to attract contributors. It’s a no-code solution that pays for itself in developer productivity."

Ask: "Should we pilot this for [high-visibility package] to test ROI?"

For Engineering Teams:

*"Dog replaces manual doc-writing with a PHPDoc linter + Markdown generator. Key benefits:

• Zero setup: Run composer require klitsche/dog and configure .dog.yml.
• Actionable feedback: Fails builds on critical doc issues (e.g., undocumented public methods).
• Flexible output: Generates Markdown for MkDocs, GitHub, or custom sites.
• Extensible: Add custom rules (e.g., ‘@todo tags must link to issues’) or enrichers (e.g., coverage data).

Example Workflow:

1. Add to composer.json (dev dependency).
2. Configure .dog.yml to scan src/ and output to docs/api.
3. Run vendor/bin/dog --analyze in CI to enforce standards.
4. Merge docs/api into your repo or deploy to a docs site.

Trade-offs:

• Not a replacement for high-level docs (e.g., architecture decisions).
• Early-stage: Expect minor breaking changes (0.x releases).
• Markdown-only: No HTML/PDF (but integrates with MkDocs for polished sites).

Next Steps:

• Try it on [Package X] and measure time saved on doc updates.
• Propose adding --analyze to PR checks in GitHub Actions."*

Visual Aid for Pitch:

Codebase → [Dog] → Markdown Docs → [MkDocs] → Published Site
               ↑
          (PHPDoc Linter)