This guide clearly belongs on the Craft Cookbook website, and will doubtless find its way there eventually.
At this moment in time, though, there’s nowhere for it to live on said site. We didn’t want to delay publication of the guide, so we decided to provide it with a temporary home here, on the Experience blog.
If you’d like to contribute a recipe to Craft Cookbook, this guide is for you. It describes what makes for a good recipe, and provides guidance on tone and language.
The purpose of this guide is to promote consistency across recipes and recipe authors. A uniform style will make the site as a whole more coherent, and—more importantly—will make life easier for our readers.
However, we don’t want these guidelines to discourage you from contributing a recipe to Craft Cookbook. In particular, if you have problems following the recommendations on tone and language, use your best judgement, and get in touch if you need a hand with anything.
If you have any questions or suggestions on how this guide might be improved, please don’t hesitate to let us know.
Each recipe must:
So what happens if your recipe runs afoul of these requirements? You have two options:
The recipes on Craft Cookbook closely follow the format of the O’Reilly cookbooks. If you’re looking for some pointers on what makes a good recipe, they’re a great place to start.
Each recipe consists of a mandatory title, two mandatory sections, and one optional section.
Every recipe must have a title which describes the activities performed by the recipe, in the present tense. Put simply, your title should be verbing something.
For example, these titles aren’t “doing” anything:
The following titles work better, and fit the guidelines:
Finally, try to avoid describing a single use-case in your title (or your recipe, for that matter). The best recipes describe a small, useful technique, which may be applied in multiple situations.
Every recipe must solve a small, clearly defined problem.
The problem section should address the user directly, and must describe the desired outcome in no more than two short sentences. If you find this to be a struggle, then—once again—it may be that what you have in mind is a bit too large for a single recipe.
As with the title, try to describe a general problem, rather than a single use-case. For example, this is a bit too specific, and does not speak in terms of the reader’s desired outcome:
Add “even” and “odd” classes while looping through a list of items.
This is a better way of describing the problem:
You want to loop through a list of items, treating even and odd entries differently.
In the words of the feature request, “Without a solution, your recipe is USELESS!!!”.
The vast majority of recipes will include a code sample; however, a solution should not be comprised solely of a block of code, with no explanation.
Provide a brief overview of how your solution works, and include inline links to further reading where appropriate: if you make reference to a Twig function, link to the appropriate page in the Twig documentation; if the official Craft documentation expands on your solution, link it up.
Most of all, your solution should be clear, succinct, readable, and actionable. Remember, the target audience of Craft Cookbook is people who need a solution right now, so don’t make your reader do any unnecessary work.
The discussion section provides additional information for those readers interested in learning a bit about the “why”, as well as the “how”.
The most important thing to understand about the discussion section is that it is optional both for the author and the reader.
Readers should be able to ignore the discussion section of a recipe completely, and still leave the site with a workable solution to their problem.
The discussion section is not simply a dumping ground for links.
Everybody has their own style of writing, and we don’t want you to suppress that personality when contributing to Craft Cookbook.
That said, there are a few guidelines that you should follow to ensure that the tone and style of your recipe doesn’t jar with the rest of the site.
Most visitors wish to solve an immediate problem, so it makes sense to use the present tense in your solution.
This is good:
You are building a “profile” page, and wish to display a user’s avatar.
This is not:
You will be building a “profile” page, and will want to display a user’s avatar.
Whilst we have no wish for this guide to descend into grammatical jargon, we should take a moment to get our pronouns straight.
Always use first or second person pronouns in your recipes. In plain English, this means you must use “I”, “you”, and “we” in preference to “he”, “she”, “it”, and “they”:
I often assign a complex filter to a variable for later use.
You need to select a random entry from a section;
This retrieves all of the entries from the section you specify.
First, we retrieve all the future entries from the blog section.
If any of the above is unclear, or you’d like our input on something, please don’t hesitate to get in touch. We’d love to help you add your recipe to Craft Cookbook.
The internet. ↩︎