phusion
Usability improvements
There seem to be people who are frustrated with the library because they experience more friction with finding what they want. Two examples are:
- https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/#comment-2522901481
- https://www.phusionpassenger.com/library/walkthroughs/deploy/python/ownserver/apache/oss/el7/deploy_app.html#comment-2526767213
The most common complaint is that people can't Ctrl-F anymore: there is a lot more content now and everything is scattered over multiple pages.
We can't do anything about the Ctrl-F, but it seems a lot of confusion from intermediate/advanced users comes from the fact that the walkthroughs and the guides are aimed at different audiences. However, it's too easy to end up at the walkthroughs, and so the intermediate/advanced users who expect short and concise information get frustrated. Maybe we can solve this by making the distinction clearer by renaming 'Walkthrough' to 'Tutorial' and by renaming Guides/Topics to 'Manual Topics'.
Another problem is that the Passenger Library isn't integrated enough with the main website.
We can't do anything about the Ctrl-F
Actually we did, the search box is the new Ctrl-F and it's placed more visible on entry.
confusion regarding walkthroughs and the guides
As discussed, renaming to improve. But the rename commit https://github.com/phusion/passenger_library/commit/165fb1c40466e47816caf2ee6196b6f1e53e69a6 is incomplete (walkthrough still appears in several places).
In commit 0ab581fa7e48f0, I made the distinction between tutorials and topics more explicit. The reader now has to explicitly choose one based on his experience level. Maybe this will reduce the confusion.
Another thing I've noticed in the analytics is that the most frustrated people don't read. They scan the page but they don't stop and think "hm maybe I should check out that specific section's index and see what's there". They have some kind of expectation on where something is supposed to be, and if it isn't there they either keep trying to do the same thing or they leave in frustration.
The search is still a hit-or-miss. If they search for a topic and they find a page with background information, then they don't navigate to the section index to see whether there are other articles that may be more relevant. They give up in frustration.
For example, there was a user who was looking for the APT package name. I think he searched for "APT" and ended up at https://www.phusionpassenger.com/library/install/apache/apt_repo/. That page doesn't display the APT package name, but it does link to the installation guide. The guy didn't go to the installation guide, filed a complaint and just left. I've made changes which hopefully solves this particular case.
So in the background information pages we need to better consider what the user may be looking if he ends up there as part of a search, and link to relevant pages more prominently.