Author's Guide: How to Write Cookbook Recipes
Author: Ian Darwin
There should be one place to look for information on writing recipes.
In fact there are two.
All the information about what to write and how to word it is
on the page you are now reading.
All information about formatting using our Wiki-subset markup is
[[Wiki Markup Subset for Cookbook Site|here].
This page is a work in progress and will grow;
if you wrote any other O'Reilly Cookbook (or even read one) please feel free to Comment and we'll incorporate the best comments here.
As a general approach, we don't want recipes that show copy-and-paste creation.
Recipes that start off in the form
- Create a new Android Project.
- Call the Activity class MyABCActivity.
- Replace the MyABCActivity with this text"
and continue with a verbatim code dump of MyAbcActivity,
with dozens of lines of imports and with "// TODO auto-generated method" comments left, in sink automatically to the bottom
of the barrel.
Recipes that instruct the reader as to why the Activity has to implement
a given method, and both discuss and illustrate what should be in that method, will rise to the
editor's attention when it's time to choose recipes for inclusion
in the published work.
Writing Recipes for Cookbook Site
Here are some general thoughts on Cookbook Recipes. See also the FAQ page (link in the menubar on every page).
- Length: A Recipe should be from one to three pages in the printed book. Only go outside that if it's important for didactic purposes.
- The Problem and Solution should both be short; the Solution should be the bulk of the recipe.
- A Recipe should describe how to achieve one task. Good examples: How to find the location from the GPS; how to display the location on a Map; how to save location data to disk or database. Bad examples: How to write a complete GPS application (too long); How to add two BigDecimal values (too short).
- See Also section: don't feel you have to limit yourself to O'Reilly books. We recognize that there are many other good publishers of technical books.
Site Rules for Cookbook Site
Please save your work often. Do not type in a whole new recipe from scratch at one sitting, as the web conversation may time out. Save and re-edit every 15-20 minutes or so.
Although we use Wiki Markup, this is not a true wiki.
The contributor of a Recipe has certain rights over it, including
that it won't be modified by other users. Anybody can comment
on a recipe, and the owner will be notified, but only the owner
and the site editor(s) can make changes to a Recipe.
We hope to add a feature to allow you to let others edit your recipes.
Of course we reserve the right to remove offensive or dangerous content.
Style Notes - Text
The Title should be short, concise, and explain what to the casual reader what the recipe is about. All non-trivial words should be capitalized. Do not end with punctuation.
The Statement of Problem section should be one or two sentences, beginning "You want to..." or "You need to" or "You can't ..." or similar wording. Do not pose it as a question. End with a period.
The Solution section should be one or two complete sentences mentioning either the approach to the solution or the API pieces to use.
The Discussion section should be the bulk of the Recipe, and will (usually) include at least one code fragment.
More to come...
Please avoid comma splices, like "Above is the code, here are the parameters" - that should be two sentences, or two clauses with a semicolon, not a comma, between.
Style Notes - Code
Remember to put <source lang='java'> and </source> around multi-line code samples, and <tt> ... </tt> around inline code.
We are pretty tolerant of code style, but please be consistent.
Indentation - while I am a Unix greybeard and thus use tabs instead of spaces in my code, detabifying your code before you paste it will make it easier to tweak without repasting (but maybe that's a bad idea anyway), because the browsers interpret a single tab while typing as a request to move to the next field. At the very least, use only spaces or only tabs in your code; this will also ensure consistent spacing in the printed edition!
Site Tech Notes
If you click Save and you wind up back in the Edit page, 99% of the time it's because you forgot to fill in the Summary of Changes (just above the Save button). Scroll down and look for the red!
If you get a message like "Edit Failed. Another user has edited the data",
it's probably because one of the editors made some changes at the same time. We generally check to make sure the owner of a recipe isn't logged in, to avoid this; sorry if we ruined your day. DO NOT RESBUBMIT the edit page, but start a new tab and click Edit again, copy and paste your changes over.
Do not use the Back button to go back into an Edit page; This can trigger the "Another user has edited the data" problem when you go to save!!
The site is built in Java using JBoss Seam 2.