Guides Laravel Package

Product Decisions This Supports

• Build vs Buy: Avoids reinventing the wheel for documentation pipelines—ideal for teams needing structured, maintainable docs without custom development costs.
• Roadmap Alignment: Enables automated, versioned documentation generation integrated into CI/CD, ensuring consistency across releases and reducing manual upkeep.
• Use Cases: Best for PHP libraries/frameworks requiring publishable, multi-format manuals (e.g., API docs, user guides) where reST is the source format, and extensibility for custom directives is critical.

When to Consider This Package

• Adoption Criteria: Use when your team relies on reStructuredText (reST), needs flexible output formats (e.g., HTML via plugins), requires CI/CD automation, or demands extensibility for domain-specific directives.
• Look Elsewhere If: Your docs use Markdown (opt for MkDocs or Docusaurus), require interactive elements (e.g., live code editors), or are simple enough for static site generators like Jekyll. Also avoid if reST adoption would create significant learning curves for your team.

How to Pitch It (Stakeholders)

Executives: "This tool automates documentation generation, ensuring consistent, professional outputs that update automatically with every release. It eliminates manual copy-paste errors, reduces engineering overhead, and delivers polished, up-to-date user guides that improve customer trust and support efficiency—all while integrating seamlessly into our existing CI/CD workflows."

Engineering: "Guides provides a battle-tested, extensible pipeline for reST content: parse → transform → render. Its pluggable architecture lets us customize directives for our needs, and CLI-first design makes CI integration trivial. MIT-licensed, lightweight, and designed for PHP ecosystems—no vendor lock-in or heavy dependencies."