Re: content for a software "cookbook" ?

Subject: Re: content for a software "cookbook" ?
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>, TechWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 3 Feb 2016 15:49:41 -0800

I had a section of a developer's guide I was calling a cookbook, but
at a certain point I renamed it "Intermediate programming: common
patterns" as that was more descriptive. "Programming fundamentals"
covers concepts and syntax for individual objects and functions as
well as an abstract overview of programming rules and best practices.
The intermediate section combines those objects and functions in
typical ways, following best practices and explaining non-obvious
choices as necessary.

I might still add a cookbook at some point to hold miscellaneous code
snippets that could be useful to advanced users. That stuff would be
more like the Atlassian model.

On Wed, Feb 3, 2016 at 3:21 PM, Monique Semp <monique -dot- semp -at- earthlink -dot- net> wrote:
> Hello, WR-L-ers,
> This is actually a two-part question:
> 1. Can anyone provide a pointer to info about what content belongs in a software âcookbookâ?
> 2. I think what I want to write is a âcookbookâ, but perhaps thereâs a more appropriate title/format (see below for info about the content Iâm writing)?
> For question 1:
> I was surprised to see nothing about âcookbooksâ in the Microsoft Manual of Styleâs âTitles of Publicationsâ section (page 152 in edition 3). So I went looking, and found some info, but Iâd like a bit more if itâs available. Hereâs what Iâve found so far:
> * is an OâReilly cookbook. On page 2 it explains that a recipe describes how to perform a particular task, and that within each recipe are four sections: Problem, Solution, Discussion, and See Also.
> * is Atlassianâs âCookbook Documentation Templateâ, and has basically the same four sections that OâReilly has, but renamed: Challenge, Solution, Discussion, and Related Challenges.
> For question 2:
> Given the above (albeit limited) info about a software cookbookâs contents, Iâm not actually positive that a âcookbookâ format is appropriate; maybe itâs only a nifty title but the content is better titled as something else?
> Iâm writing an internal doc for software *developers* (so not dedicated QA engineers) to explain methods and best practices for writing various sorts of tests, within the companyâs development/test environment. The focus is not a generic âhow do I write test codeâ sort of thing, but things such as:
> * Advice for: choosing among the companyâs several existing test frameworks; choosing an appropriate existing test to use as a model; integrating the new test into the test/build environment; etc.
> * Command reference for test driver scripts.
> * Annotated examples of representative tests for each test framework, and for several different sorts of software functions. (This âannotated exampleâ seems to stray the most from the cookbook format that the two above references provide.)
> * Etc. (Not sure of all the topics yet)
Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

content for a software "cookbook" ?: From: Monique Semp

Previous by Author: change layout for multiple slides in PowerPoint 2016 for Mac
Next by Author: Re: Need Feedback from Technical Editors
Previous by Thread: content for a software "cookbook" ?
Next by Thread: STC Certification

What this post helpful? Share it with friends and colleagues:

Sponsored Ads