Revise PHP How To Guides

[fg-j]

Now that Paketo's docs have been split up into categories: Concepts, Reference, and How To, it's a good time to bring fresh eyes to each type of documentation and help them fulfill their intended purposes.

The guiding ideas for what makes a good How To guide come from Divio.

Some key takeaways about How To guides:

• How-to guides take the reader through the steps required to solve a real-world problem.
• How-to guides are wholly distinct from tutorials and must not be confused with them:
  • A tutorial is what you decide a beginner needs to know.
  • A how-to guide is an answer to a question that only a user with some experience could even formulate.
  • A how-to guide should not explain things. It’s not the place for discussions of that kind; they will simply get in the way of the action. If explanations are important, link to them.

In other words, if someone comes to a How To guide, it's probably because they have experienced a problem they don't know how to solve. Therefore, Paketo's how-to guides shouldn't just enumerate or expose a buildpack's features (e.g. the existence of a certain configuration environment variable). They should each address a user's problem, and (probably) use buildpack features to achieve the desired result. Many buildpack users' problem is, "I have a _______ app and the buildpack isn't building it correctly." So sections like "Build a ________ app" might be useful. (e.g. "Build a React app", "Build a Rails app")

For the sake of consistency, each guide title in Paketo docs should complete the sentence "How do I ..." . For instance, use "Install a Custom CA Certificate" instead of "Installing a Custom CA Certificate" or "Custom CA Certificates"

For some examples/inspiration, see the Paketo Go how to guides, which have been revamped with Divio's guidelines in mind.

Specifically, for this issue, the @paketo-buildpacks/php-maintainers should have a look at the How To documentation for PHP and see how the guides there can be improved.

EDIT
We also want to add a Getting Started guide to https://paketo.io/docs/ that shows a PHP example.

[dmikusa]

I'm OK with what is in there now. I will keep an eye out for possible new additions while talking to folks about the buildpack and answering questions on Slack.