You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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/python-maintainers should have a look at the How To documentation for Python and see how the guides there can be improved.
The text was updated successfully, but these errors were encountered:
fg-j
added
the
maintainer-cta
An issue that asks Paketo subteam maintainers to take action (not just Content maintainers)
label
Sep 8, 2021
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:
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/python-maintainers should have a look at the How To documentation for Python and see how the guides there can be improved.
The text was updated successfully, but these errors were encountered: