recipes page should be rewritten to provide actual recipes

[jralls]

Here's a "recipe":

Citing a Physical Artifact

The following example illustrates how to cite a physical artifact, such as a book. Evidence for Asa Phillips is found in a > book authored by Helen Kelly Brink. The book doesn't have a URI, but the URI for a description of the book is "https://familysearch.org/platform/sources/KKK-KKKK".

That neither explains how to cite Brink's book nor how to connect the (non) citation to Asa Phillips, never mind that, unless it's a compiled genealogy it more likely describes an event in the life of somebody named Asa Phillips. (From the specification, it would appear that a source reference containing the URI of the source should be added to the Asa Phillips Person entity's source list and to the source lists of whatever conclusions depend upon that source.)

A recipe is "a formula or procedure for doing or attaining something" (http://www.merriam-webster.com/dictionary/recipe, accessed 10 Jun 2012). Your recipes are of the form: "Cake: Bake a cake" or "Cake: example of baking a cake". That won't even help an experienced baker get you the cake you want.

If you're going to have serious recipes, each one deserves its own page. It should include the list of XML elements that are affected -- the ingredients, if you like, and detailed instructions for generating each element, including how to link between them. Detailed and complete examples would be very helpful.

[EssyGreen]

Although I think "useless" is a bit strong, I do wholeheartedly agree with @jralls here:

A recipe is "a formula or procedure for doing or attaining something"

I think you also need to include full examples of the source and affected records before the citation is added as well as after so that omissions can be seen. For example, if citing from a birth certificate then show say the mother, father and child records before the citation; show a realistic example of a certificate; show which fields go where and which fields go no-where; show how the user should justify that the people in the cert are the people in the tree etc etc

[stoicflame]

Nice.

Does anyone mind if I edit this issue to better reflect what's being requested? I think a title like "recipes are useless" is useless. :-)

[EssyGreen]

lol! I'd support that :)

[jralls]

I don't, and your change is inaccurate and self serving. This is not a feature request, it's a defect report. The so-called recipes currently on the website are not recipes. They are either placeholders, e.g.

Describing a 1930 Census Online Record

Example for describing an online 1930 Census Record.

I'm unable to come up with a description of the entries like the one quoted in the original report that is both more descriptive and not unacceptably rude, but I'll borrow from a related post of Sarah's: In a comment to #120, she said that the recipe was like the chemical formula for a cake. That's not the case. The recipe says "There's a nice picture of a cake on the frontispiece."

A chemical formula would at least be in some sense useful, in that it would contain some amount of additional information.

[stoicflame]

Wow. Okay. My apologies for taking the liberty of changing the title, I didn't mean to offend.

So help me out. Do you think a title like "recipes are useless" is a good title for a "defect report" (your words, not mine)?

Having seen a lot of defect reports, my opinion is that a good title should give an indication of the work that needs to be done, so I was attempting to reflect that.

[jralls]

Short answer: Yes. It accurately and succinctly describes a very serious deficiency in the project documentation.

My experience with defect reports is that good ones describe accurately the bug, not the solution. When it's possible for the reporter to do so, they may include a patch. In more extreme cases where the problem is the result of a gross conceptual error that requires a rethink and redesign, a patch isn't really feasible. In such cases titling the bug prescriptively (i.e., "indicating the work that needs to be done") overly constrains the solution. The goal of a defect report is to make the responsible engineer understand what's wrong so that she can find the best solution. That's especially true in the case of "rethink and redesign" level defects.

Look over the open bug list for Gtk+: There were 3338 bugs on that list when I pulled it. Only a few of the summary lines are prescriptive.

"Useless" pretty accurately describes the entries on the recipe page, and my original report included a description of what I think a recipe needs to include. The title needs to be succinct, but in the body of the original report and in my comment above I've explained more thoroughly my reasoning.

Unfortunately, the recipe page falls in the "rethink and redesign" category. I tried to describe in the original post what a recipe needs to look like; Sarah had a go in her comment on #120 (the one that I borrowed from above). You can either accept the criticism and rewrite the recipes so that they're actual recipes and therefore useful, or you can close the issue as a "won't fix". It's up to you and your managers.

[stoicflame]

So my concern is that a statement like "recipes are useless" doesn't amount to much more than commentary, voicing your personal frustrations with life.

I think as moderator it's fair to make adjustments to the issues list to make sure it's used for its intended purpose. And I think it's fair to state that the issues aren't to be used to voice personal gripes and frustrations about the project. You can use your own blog for that, yes?

You've made some great points here that I'd like to make sure get addressed so I'd rather not close the issue.

C'mon man. I'm sure you can take a deep breath and come up with a suggestion for a title of this issue that more neutrally reflects the issue, yes?

[EssyGreen]

@jralls

Sarah's: In a comment to #120, she said that the recipe was like the chemical formula for a cake. That's not the case.

You misquoted me - I said it was a chemical compound (not formula) - a formula would give you an equation/recipe/method for coming up with the cake. The compound is just the sticky mess in the test tube :)

It accurately and succinctly describes a very serious deficiency in the project documentation.

I think the term "useless" is "useless" unless there is a context for which they are to be used ... so "useless for doing XYZ" yes but "useless" on its own is yeah useless :)

So, what was the purpose of the recipe book? And in what way does it fall short in your mind?

Here's my take on it:

• Examples are too simplistic and unrealistic
• Recipes don't show a before and after so hard to tell what is being demonstrated
• No details of the sources are shown so it is impossible to tell whether the data in them was successfully retained/represented/coded up in GEDCOM X
• There is no indication of the genealogical process ie what was the researcher attempting to do

[jralls]

You misquoted me - I said it was a chemical compound (not formula) - a formula would give you an equation/recipe /method for coming up with the cake. The compound is just the sticky mess in the test tube :)

Sorry, I should have copied/pasted. Among U.S. chemists (meaning scientists who research in the field of Chemistry, not merchants who sell pharmaceuticals) a "chemical formula" is something like C₂H₄OH (for ethanol), where a "chemical equation", something like 4CO₂ + 7H₂ -> 2C₂H₄OH + 2H₂O describes the chemical process. "Two peoples divided by a common tongue" (variously attributed to either Shaw or Churchill). ;-)

Anyway, How else you'd describe a statement like

The book doesn't have a URI, but the URI for a description of the book is "https://familysearch.org/platform/sources/KKK-KKKK". besides "useless"? Meaningless, tautological, content-free, and the programming "no-op" come to mind.

How about "Recipes aren't recipes" for a subject?

An aside: The FamilySearch citation URLs don't resolve to DC -- or any other machine-decodable -- structures, so they're not appropriate in this context. They're provided as search results, and they don't even point into the FHL catalog! Google Books will at least provide a Bibtex, Endnotes, or RefMan export of the citation, which can be easily machine translated into DC.

[EssyGreen]

I guess what I was trying to say is that we seem to have a picture of the chemical compound (ie substance) rather than either the formula or the equation. In baking terms we have a representation of the sticky mess in the bottom of the baking tin with the odd currant poking out and a bit of brown stuff that looks like chocolate, rather than a list of ingredients and a method for transforming them into said sticky stuff :)

I do agree with you tho' although I also agree with Ryan that your comments could do with a positive twist to turn the negative into remedial action.

[jralls]

OK, let's stick with baking. You seem to have a lot of mental images of cakes gone wrong! ;-) I've never seen any pictures like that in cookbooks, though... they always make sure there's a perfect, beautiful example ready when the photographer comes round.

I've proposed a couple of remedial actions in comments. If Ryan really wants a prescriptive subject, I propose "Recipes page should be rewritten to provide actual recipes".

[EssyGreen]

I've never seen any pictures like that in cookbooks, though... they always make sure there's a perfect, beautiful example ready when the photographer comes round.

Sort of my point in that our genealogy recipe book is giving the sticky mess without the method. The "nice picture" was in the first part of my example (equating to the model diagrams).

[jralls]

;-)

[stoicflame]

I propose "Recipes page should be rewritten to provide actual recipes".

Changed. Thanks.

[jralls]

Hmm. Still showing up here as "recipes should include more detail".

[EssyGreen]

Er guys could we spend a bit more time addressing the problem rather than talking about the phraseology of the issue!

[stoicflame]

Hmm. Still showing up here as "recipes should include more detail".

That was weird. Now?

[jralls]

Yup, now it's changed.