TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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:
>
> * https://books.google.com/books?id=sB8OoH33seYC&pg=PA127&lpg=PA127&dq=what+sections+go+in+a+software+cookbook&source=bl&ots=muQyyt1Xf0&sig=TbxBOAgsj-xzPFeDbzjkWw9yVJg&hl=en&sa=X&ved=0ahUKEwjFtLCF19zKAhUEWCYKHelWBPAQ6AEIPzAF#v=onepage&q=what%20sections%20go%20in%20a%20software%20cookbook&f=false 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.
>
> * https://cwiki.apache.org/confluence/display/DIRxSRVx11/Cookbook+Documentation+Template 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 | http://techwhirl.com
