content for a software "cookbook" ?

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

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)

Thanks for your input!
-Monique

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

Previous by Author: Re: Most recent file modified in a folder, in a table
Next by Author: Re: STC Certification
Previous by Thread: change layout for multiple slides in PowerPoint 2016 for Mac
Next by Thread: Re: content for a software "cookbook" ?


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

Sponsored Ads


Sponsored Ads