Laravel backup documentation unclarity

Non-specific depiction of a 3 column web page, with a magic wand in the bottom right shooting stars encircling the web page, to illustrate magic.

NB! I am _not_ critical of the project or the functionality or even the documentation on a whole. It’s mostly great! Now, back to the story.

I had an assignment at work that consisted of finding a viable database backup solution for a Laravel project. One of the suggestions was to use laravel-backup from Spatie.

I was reading through the Github readme in an attempt to find installation instructions. I found a link, below the title “Installation and usage”, to their official documentation, with the text “You’ll find installation instructions and full documentation on”

Screenshot with the following text:

Title: Installation and usage
Body: This package requires PHP 8.0 and Laravel 8.0 or higher. You'll find installation instructions and full documentation on

Clicking that link brought me to the documentation’s introduction page. But on that page there’s no mention of installation instructions or links to the same. There’s a sentence stating what to do _after_ installation; “Once installed, making a backup of your files and databases is very easy. Just run this artisan command:”, but no mention on where to go to install the thing.

Screenshot with the text:

Sub header: One day you'll thank us for this
Title: Introduction
Body: This Laravel package creates a backup of your application. The backup is a zipfile that contains all files in the directories you specify along with a dump of your database. The backup can be stored on any of the filesystems you have configured. The package can also notify you via Mail, Slack or any notification provider when something goes wrong with your backups.

Feeling paranoid about backups? Don't be! You can backup your application to multiple filesystems at once.

Once installed, making a backup of your files and databases is very easy. Just run this artisan command:

Now, I know there’s a nav to the side that house the “Installation and setup” link, but I had to do a bit of scanning to find it.

My personal, subjective, expectation was that when I clicked the link in the text “You’ll find installation instructions and full documentation on” I would be taken to a page explaining (or at least linking from there) to the installation instructions.

I don’t really know what happened here; It could have been a mistake. I may have unrealistic expectations. But, I refuse to believe it was intentional. Mainly because if there’s text that says “Go [here] to do [this]” and it brings me to a page that _technically_ has information related to the [this], I feel at worst misled but at best frustrated that the information isn’t available.

My suggestion as how to fix it; Don’t mix “Installation instructions” and “full documentation” in a sentence, unless the link brings you to a page that contains both. Without having to click even more links. Or having to hunt in a nav menu on the side.

Or, even better; Separately link the “Installation instructions” to the page containing the installation instructions and the “Full documentation” to the full documentation.

I just needed to bring this, albeit small, frustration up. I am a creator of software and documentation myself and know about the struggles when it comes to this. So when I point things like these out, it’s because I personally would want to avoid similar situations in my own work.

Leave a comment

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.