As a published technical writer, I’ve had my share of experiences working with a publisher and its editors for a period of seven months. For my own sanity, I’ll post some of my experiences in this series of blogposts on Experiences with Being Published. I feel these stories can be quite entertaining, and I might even get a smile on my face when I look back at these stores in a couple of years’ time…

I thought writing a book would be a lot of fun because I am quite creative. That turned out to be quite an assumption…

About Cookbooks

A Technology cookbook, as it turns out, is a very specific book. Just like any ‘normal’ cookbook, it contains recipes. The term cookbook is used metaphorically to refer to any book containing a straightforward set of already tried and tested recipes or instructions for a specific field or activity, presented in detail so that the reader, who is not necessarily an expert in the field, can produce workable results.

As it turns out, my publisher is very specific about what a cookbook should look like on the inside.

The rules

Before starting writing my first chapter, I received a sample chapter with some comments on how to do things. After receiving my first feedback, though, I realized the list of rules for chapters and recipes is quite long. I particularly struggled with the following rules:

1. Every chapter starts with a short introduction followed by a list of all the recipes in the chapter.
2. Every recipe has the same headings in the same order; Getting Ready, How it’s done, and How it works. None of these headings may be omitted. Their order must not be changed. Additional headings may be added after these headings: There’s more and See also. In that order.
   For recipes that aren’t that technical, this is a burden Three recipes in particular (Chapter 1’s “Creating the right trust”, Chapter 11’s “Choosing the right AD FS Farm deployment method” and Chapter 12’s “Choosing the right Hybrid Identity authentication method”) proved opportunities for debate with the content team.
   Eventually, the headings grew on me, when I realized I could interpret them the way I wanted to. I mean; Getting a coffee is a good way to get ready, too…
3. Between every heading and a subheading, there needs to be text. This is when you add standard non-creative sentences in a book, like “Use this recipe to <title heading here> “, “This is how to <title heading here>”.
4. You can’t have multiple Warning, Information or Tip blocks without having paragraphs between them. Guess how many of these blocks I removed, just to comply with the rules that were punt in place to uphold the quality of the book…
5. When using steps in a graphical user interface in a recipe, at least one screenshot needs to be added between the steps in the recipe.
6. Screenshots require a lead-in.
7. Screenshots are always centered and the publisher adds a border.
   For three flowcharts in the book, I debated for weeks to not get this rule applied. Eventually they agreed, but only after I sent the PowerPoint version of the flowcharts by mail, so that they could create sufficiently high-resolution images to the book to circumvent jarring of edges.
8. You can’t quote the Microsoft KnowledgeBase or link to it, because there is no permission to do so, apparently.
9. The See also section of a recipe is to be used to point to other recipes in the book. However, the links in the PDF of the book, as a rule, only point to the start of the chapter. This makes for a lot of unnecessary scrolling for people wanting to use this functionality. I guess it’s why one of the other rules is “Chapters may not exceed 50 pages”.
10. You can add links in the See also sections of a recipe, but the links will not be shortened. Apparently, if a reader wants to use the link, it will have to be typed manually into the browser…

The sample chapter

In the end, the sample chapter proved a disaster. The introduction for the chapter came after the list of recipes. Its comments around screenshots didn’t mention any lead-ins, but instead suggested captions below the screenshot. The editing team ‘created’ lead-ins, which I subsequently had to change, because they consistently referred to the wrong action.

To add to insult, the sample chapter was shared in Microsoft Word format.

Concluding

Interestingly, when I show people the cookbook, their reaction is that its style is really ‘Microsofty’, meaning that people experience the style of the book as the style of Microsoft Official Curricula.

I feel it’s positive feedback. I guess I’m ready to contribute to these now, too. I’ve been a Microsoft Certified Trainer (MCT) for the last five years, so why not.

Picture by Sandwich, used under CC BY-NC-ND 2.0 license. Adjusted in size.

Learn the intricacies of managing Azure AD, Azure AD Connect as well as Active Directory for Identity and Access Management (IAM) in the cloud and on Windows Server 2019.

Get up to date! Get your 620-page, 147-recipe copy of the Active Directory Administration Cookbook, today. Buy it from Packt directly, or through your favorite local reseller.