Currently Available: Need a skilled Software Developer for your next project?
Categories
Laravel

Separating Public and Internal Documentation for Laravel Packages

Laravel package maintainers write for two main audiences: developers who install and use the package, and people who work on its code and releases. Public documentation helps package users install and configure the package. Maintainers and contributors use maintainer documentation to test changes, review contributions, and publish releases.

“Internal” often means maintainer-facing, not private. A public CONTRIBUTING.md can explain how to run tests, while confidential credentials or incident details need a location that only authorized people can access. Separating documents by reader and task keeps the package’s public instructions focused without hiding useful development guidance.

Organize files by reader and task

There is no Laravel-required folder structure for documentation. Use a layout that makes the package users’ starting point obvious and gives contributors a clear place to start. For example:

README.md
docs/
  installation.md
  configuration.md
  usage/
  reference/
CONTRIBUTING.md
MAINTAINING.md
CHANGELOG.md
SECURITY.md
src/
tests/
workbench/

The README.md introduces the package and gives users a short path to a working installation. The docs/ directory holds deeper user guidance. CONTRIBUTING.md explains how to make and test changes, while MAINTAINING.md records repeatable release work. These are suggested roles, not required filenames; GitHub also supports contributor guidelines in docs/ or .github/, as its contributor-guideline documentation describes.

Laravel’s package-development documentation covers implementation concerns such as service providers and configuration. It also covers migrations and publishable resources. The Laravel package skeleton also shows a repository development path with tests and a workbench, a local Laravel application used to test a package during development. These details help contributors work in the repository; package consumers need the corresponding installation and usage instructions.

Keep the README on the user’s path

A package README should answer the questions developers have before and during initial use: what the package does, which PHP and Laravel versions it supports, how to install it, what setup it requires, and where to get help. GitHub describes the README as a common first point of contact for a repository, including project purpose and getting-started information.

For a Laravel package, the quick start should show the command package users run with Composer, PHP’s dependency manager, to install the package. It should include only the setup steps users need before they can begin. If the package requires a published configuration file or migrations, explain those steps. Then provide a small example of the package’s main supported use and link to detailed configuration, usage, upgrade, and reference pages.

The Spatie Laravel Permission README shows how a short README can serve as the package’s main starting point: it links to detailed user documentation and separates user guidance from contributing and testing information. Its installation instructions show how detailed setup steps can live on a separate page. A hosted documentation site is another option. Users can find one main explanation for each task.

If the README grows to cover setup variations, move those instructions to linked pages. Do the same for configuration details and examples. Keep repository test commands and release steps out of the quick start. For packages with multiple features, organizing docs by feature can help users locate the relevant instructions without turning the README into a full manual.

Put development and release work in contributor docs

CONTRIBUTING.md should tell contributors how to prepare the repository and run tests. It should also explain how to submit changes. Include the commands and checks that the package actually uses, plus guidance on updating user documentation when a change affects installation, configuration, or behavior. Keep these instructions useful to outside contributors as well as maintainers.

A separate MAINTAINING.md can describe work that maintainers repeat when preparing a release: checking compatibility information, reviewing the changelog, updating public docs, and publishing the release. This file is a practical convention, not a Laravel standard. If a package has a simple release path, a short section in CONTRIBUTING.md may be enough.

Keep CHANGELOG.md focused on notable changes package users and contributors need to understand. Keep a Changelog recommends a curated, human-readable record and clear labels for breaking changes. Routine internal work belongs in development history unless it changes what a user needs to know.

Treat confidentiality as an access-control question

A folder named internal/ does not make committed files private. GitHub states that anyone on the internet can access a public repository. Keep credentials, private incident details, and other confidential information in a separate access-controlled location, rather than relying on a filename, hidden link, or documentation-site navigation setting.

Public maintainer instructions are different from confidential records. Test commands, contribution expectations, and release procedures can help outside contributors understand how the package is maintained. Choose whether to publish each document based on its contents and audience, then make the appropriate entry point easy to find from the README.

Update the right docs when behavior changes

When a package changes, identify which reader task the change affects. A new configuration option belongs in the configuration reference; a changed setup step belongs in installation guidance; a breaking behavior change belongs in upgrade instructions and the changelog. Contributor instructions need updating when development commands or checks change. Avoid copying the same procedure into several files, because duplicated instructions can drift.

Before merging a change, check whether it changes a command or option users see, a supported version, or a setup step. If it does, update the relevant public page and release notes. For broader maintenance practices, see when to update package docs and keeping Laravel package docs current.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com

Email updates

Usually a new article and a few links I found interesting.

No spam. Unsubscribe with one click.

Leave a Reply

Your email address will not be published. Required fields are marked *