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 https://spatie.be/docs/laravel-backup.”
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.
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 https://spatie.be/docs/laravel-backup.” 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.