Authors journey writing a technical book

0
2687

The day before christmas, after nine months of hard work, we (Phil Wilkins and I) send the final draft of the last chapter we needed to review of our book Implementing Oracle Integration Cloud (ICS) to our publisher Packt. We are now in the final phase of getting the book published to print. Currently we are sorting out the final dots on the i’s and crossing the last t’s. In this blog I want to take you on my authors journey writing an technical book.

How it all started…

Last year (March 2015) I was formally introduced to Oracle Integration Cloud Service during the EMEA Partner Community Forum. I had the change to try the beta as one of the first people and when it was released in May that year I immediately saw the potential it had. A fresh new look on a dusty Service Bus that connected to Cloud / SaaS applications with Out-of-the-Box adapters. My first blog where I introduced ICS was published on the 27th of May. In the months after that I wrote a few more blogs on ICS. On the last day of December I got an email from some guy from the UK, his name was Phil Wilkins an IT architect, and there it all started for me.

“One year has passed since
our first contact”

It all started one year ago when I received that email. Phil walked around with the idea to write a book about ICS and noticed my blogs about the topic (read his story here). He contacted me with his idea to write a book and the weird thing was that I also had a feeling I wanted something more than writing blogs about it. After some email discussions, reading some of his blogs and a phone call I decided to take on the journey to write the book together with Phil.

“Doing it for the right reasons”

Like Phil also writes in his story… writing a book is not a small undertaking. How wrong was I to myself when started the journey, thinking we would be done before Oracle OpenWorld 2016. I personally worked week in, week out for three of four evenings (19:00 till 23:00) and sundays (11:00 till 18:00) and don’t even mention my summer. One more thing… don’t count yourself a rich man after the book is published. You are not getting a huge percentage of royalties of the book pricing and when a book is discounted you will get even less. Do it for the right reasons.

My reason for writing the book is reaching people outside of my network circle that normally read my blogs. People know me from being an advocate on SOA Suite, but I felt that writing this book would give me an extra boost regarding Cloud. It might even led to people seeking my professional help when implementing ICS.

Finding a publisher for the book

The first step was getting signed at a publisher. When Phil contacted me, he was already working on this. He talked to Oracle Press first which is run by McGraw-Hill. They weren’t too sure about the idea of cloud, having been unsuccessful with previous books on that topic.

Phil then contacted Packt, because of his earlier relationship with them. Because of the initial positive feedback we started with the next steps to eventually get signed at Packt.

“The first thing Packt asked us was to submit a table of contents”

We constructed a list of chapters titles we wanted to write including subsections and even an estimated page count. The idea of the book was to implement certain integration patterns using ICS and show of the capabilities of this iPaaS (Integration Platform-as-a-Service) solution. Knowing this we plotted out the title and subsections of each chapter. We discussed various examples for each chapter and decided on using plausible scenarios surrounding an Airport Schedule & Maintenance system. Estimating the page count is a lot harder. I mainly took this hard job on me and predicted the page count based a blog series I wrote on the Connectivity agent included with ICS and did some math if a specific chapter with be larger or shorter in content than that blog series.

In the end we were over estimation on most chapters usually between 10/15%, but the more advanced chapters tend to be even longer as estimated. Looking back at this we should have wrote one or two chapters in advance before estimating, because the amount of pictures, but also required styling elements will take up a lot of space. Luckily for us Packt didn’t mind at all that we run over our estimated page count as they saw that it was quality content which made to book better rather than removing content to make the estimated mark. The main reason for taking a little more effort in estimating is because the publisher will use this estimate to make an initial planning.

Divide and initial planning

Because we in this project 50/50 we divided the work. Knowing I had more technical knowledge of ICS and Phil, because of his role as IT architect, could better explain more architectural topics we divided these chapters first before dividing the rest. So when you are working with others on a book keep in mind when dividing the work who can explain which topics better.

Like I mentioned earlier in this blog our initial goal was to have it published in time for Oracle OpenWorld, but you know when reading this blog that we missed that mark by a mile. The reality my everyday live is that I still have a full-time job, I present at (international) conferences, I’m organizing meetups for the OGh (Dutch User Group) and then you have your family and sports. Oh yes and there is something as personal downtime. This all takes chunks of time from your writing schedule. Our original plan was to write an average of two pages each day, but if I would plan it again it would be an average of one page each day. Some days you write more and some days you write none.

We also found some bugs during the process of writing. The bugs delayed some chapters for a few weeks, where we even had to change the chapter’ scenario, using a workaround or even skipped some functionality. Another factor of delays due to bugs is waiting on a patch or some detailed analysis by Oracle PM.

So looking back at the past year I would suggest to do some work during the planning. Write one or two chapters to get a feeling of how long it may take and maybe work out some example scenarios.

After planning was done and a timetable was discussed with Packt. We were asked about the price of the book. The price you negotiate determines what your share will be, but don’t make it to high for people to buy.  We eventually signed our contract with Packt in february.

“Writing your first book
is something special”

Writing the 1st drafts

I finally started writing my first book, which is really something special. Like most things you can only say this ones. My first challenge was finding the right atmosphere to write. I just moved into my first real house (owned an apartment before that) and did not have and still not have office furniture. When keeping focus it also didn’t help for me to work at home. Even living alone I keep getting distracted. And working at the dinner table is also nog healthy / pleasant way to work. Lucky I had the security code of the AMIS office and discussed with Office Management that I could work at AMIS after closing hours. So what I would do is after a day of work at my customer, have dinner and return to the AMIS office to work three evenings a week from 19:00 till 23:00 and mostly every sunday from 11:00 till 17:00/18:00. I was so focussed there instead of at home. If I had a desk to work on at home I might even have chosen to work at the AMIS office.

To keep our focus at the optimal level Phil and I decided to have a weekly call to discuss our progress. Where we talked about idea’s to create the best scenario’s, incorporate best practices and just other stuff to keep in sync. When writing together you always have a person to discuss your opinions with, mostly when you get stuck on a chapter.

We aligned our writing styles, helped each other to keep focus and reduced as many differences we had.

When writing the chapters I always started with plotting out the scenario. What do I want to tell the reader without choosing technologies and the Cloud services / SaaS application I wanted to use. I really helps getting a clear picture of what the flow of the chapters should be. Then I tried to fit in the best technologies and services for that scenario. Looking at which adapter ICS supported out-of-the-box and what functionality it brought to the table. You will notice when you have chapters that are more clear to you that these chapters are easier to write and flow a lot better. After I plotted out the flow of the chapter I started creating the scenario in ICS myself and wrote the pages during the build in the same order.

Looking back at this I should have first tried if a simple scenario was working with the adapters I wanted to use, because some just didn’t, and you sometimes will discover it just ain’t going to work like you would expect. Also styling was also one thing constantly on my mind, compared to Phil I took more time on this subject. Phil for instance needed to correct more or these parts when chapters were reviewed.

After completing a chapter we first send the chapter to the other person to review each other’s work before sending it to Packt. This is a perk when working together. Whereas I reviewed mostly on images, Phil refined my English wording. This helped us get more quality chapters before Packt has even seen the original content. I feels exciting when you finally send in a chapter. It took us 7,5 months to write all the first drafts because of the way worked and the bugs we encountered, but looking back it this it only cost us 1,5 months to write the second drafts. The total page count of the book eventually hit 450 pages, and with a preface and thirteen chapters that is slightly more than 30 pages per chapter.

So contact wise we were half way, but in reality we were much closer to the finish line. Hitting this first milestone also mend we would receive our first advance on payment.

Processing review comments and writing the 2nd drafts

Every book has one or more technical reviewers that below to the audience of the book. Before working on the second drafts the first drafts were reviewed by one technical reviewer. Thanks Rolando Carrasco for reviewing our book. For us this was an fairly easy task. We got positive feedback and quality suggestion on where to make adjustments and additions.

Because we wrote about Cloud the product got a lot of updates during the year. So we also went over the scenario’s to check if everything was still working and changes screenshots where needed. Like Phil also explained in his story is that we seen comments about missing context when processing the first few chapters. We found out that the preface was not send to the reviewer where most of his comments were already explained. We dismissed some of these comments and mentioned to Rolando that we addressed them in the preface, which he received shortly after that, but took this as a lesson and gave the reader more context in upcoming chapters.

Most changes where on adding some more screenshots to give the reader more context and also more text to clarify the things we were discussing. So within two weeks we processed all the comments and then it was off to the publisher for the final stage of the publishing process.

So are we there yet…

We are now in the pre-final phase off the book. This means that a technical editor working for Packt is going through the chapters and checking for the final styling and placing page breaks at the best spots in the document. We received some of the chapters already. During this process you will receive the pre-final documents. The are in the final ebook form. As an author you can proofread the work that the technical editor did and decide if it looks and reads like you as an author wants. This phase is important, because it is so final, and you should read every word. I noticed that some things are changed to the text and also some comments are placed in the PDF that I needed to address. Some things were not to my liking and I addressed those back to the technical editor. One tip is to compare the PDF of the pre-final chapter you receive with the last draft you send to Packt.

Going forward

How it now looks our book will be published in the coming weeks, end of January 2017, but does this mean we are done? No, we will continue to write additional material, initially for the blog (oracle-integration.cloud) but we are exploring the idea of a living book where the book version will undergo quarterly updates. But time will tell as to whether this makes a difference.

The book can be found at Packt and Amazon.
But probably it will also be available through Safari (subscription service).

SHARE
Previous articleOTN Appreciation Day: Error Hospital / Resiliency in SOA 12c
Next articleFor Each activity for processing batches – ICS Definitive Guide
Robert is an respected author, speaker at (international) conferences and is a frequent blogger on the AMIS Technology blog, the Oracle Technology Network, and participates in OTN ArchBeat Podcasts. Robert is an member of the board of the Dutch Oracle User Group (nlOUG) and also organizes SIG meetups. He also works closely with the SOA Oracle Product Management team by participating in several Beta programs. In 2017, Robert was named Oracle Developer Champion, but also hold the Oracle ACE title for SOA and Middleware, because of his contributions to the community. He is co-author of the first Oracle PaaS book published, which was published in January 2017. His fascination for using the latest technology had led to the research of Blockchain to replace the currently used B2B patterns and tooling.

LEAVE A REPLY

Please enter your comment!
Please enter your name here

This site uses Akismet to reduce spam. Learn how your comment data is processed.