In January we presented our 1st online training, looking at API Design and use of Apiary and Swagger. Things went well until near the end where for some reason voice and video dropped for no apparent reason. Our coordinator Lindsay kept the recording going and soon as we reconnected I continued the session and went through the Q&A.
So if you missed the end of the end of the training, please do check back with the recording.
If you missed the training – we’ll be rerunning in March – go here.
For those on the training will have seen at the start of the training links to my social media profile, so happy to try respond to any further questions.
We are also scheduled to run the session again in a month or so.
One of the questions received during the session I thought worth mentioning was when would Apiary support Open API 3.0. Well according to their blog very soon, looking forward to it as the OAS 3 does look a little cleaner.
My next Packt project (via O’Reilly) is not a book, but a short online training course about good API design, API 1st and some tools that can support an API 1st methodologies. Register for the session here.
It includes a closer look at cloud tools such as Oracle’s excellent Apiary (sorry if this sounds like a sales pitch, but it is a good tool and the words of the found of RestLet confirm this) along with SwaggerHub and a few other options.
A good API goes beyond just the payload definition and I’ll walk through the other considerations and explain why these other areas are important.
After months of labour, the arrival of new family members for a couple of the authors the Implementing Oracle API Platform Cloud Service book as finally been published. The book has been included into Packt’s Expert series so, earns(?) the privilege of having photos of the authors on the cover. The book can be purchased directly from Packt (go here) or from book retails such as Amazon (here).
It has been an interesting experience. Whilst working as part of a team of four authors lightened the writing load, a lot more energy went into communication so things were lined up. If you want a challenge, why not read the book and try to work out who wrote which chapters!
Now the big news, we have just agreed with Packt Publishing to write a book around Oracle’s new API Platform Cloud Service (APIP CS). This is going to be more of a team effort with 4 of us working on the book. With all the authors working for Capgemini as well it should be a lot easier in terms of effort The book is being targeted for late this year to be published so that we can cover the major features being released this summer which will make the product a lot more rounded and complete.
The book will also bring in another initiative that has been running in a fairly low profile manner, but starting to shape up in the form of something called OMESA (OMESA.io). This initiative is a cross party approach to define a reusable reference architecture that engages both the legacy landscape along with API driven / microservices based contemporary solution delivery.
We will of course continue to blog about ICS at https://oracle-integration.cloud
We have just supplied our publisher with the final draft of the final chapter in our book about Oracle Integration Cloud Service (ICS). Before we get too chilled out waiting to see the printed article as Packt Sort out the final publishing I thought it might be helpful to share some observations from our experiences.
Let’s start with some background. I have been acting as a peer reviewer for Packt for some years now, and in fact Packt had approached me in the past to write a book, however I had declined their proposals as I didn’t want to write on a subject that people had already written about. So when I was introduced to ICS, this felt like a good subject to write a book on, certainly represents something that it is going to have a significant future and deserved a book to help people get beyond a basic user guide.
Choosing to write a book is not a small undertaking, so make sure you’re going to do this for the right reasons. Let’s be honest, very few books make much money. You have to be lucky, writing a subject you know us going to be game changing (think Gang of Four and Thomas Erl) or have a definitive text on the next big thing that everyone will use. Publishers also run promotions, discounts and give aways, some more than others, but that will all eat into you share, not to mention unless you self publish or you’re a rock star author you will not see big percentage royalty rates coming your way.
So first steps, for us was to get a publisher on board, given it was an Oracle product I wanted to talk to Oracle Press (or here) first which is run by McGraw-Hill. They weren’t too sure about the idea, having not been successful with previous cloud books. So we went back to Packt, they do have Oracle based books, and I had a relationship there.
With some initial positive feedback, I needed to get things moving. Thinking through this I concluded that the entire book alone could be a lot of very hard graft when working with a new product and I didn’t have the access to the same level of resources working for a customer organisation as you can with an Oracle partner company. So I needed a co-author who was involved with ICS, and ideally working for an Oracle partner. I had seen Robert van Mölken blogging about ICS, and working for AMIS suggested he would be a very capable person, not to mention AMIS is a respected partner. Robert has shown himself to be more than capable, and getting him signed up to the idea was a good call.
Next, was to start properly developing the idea, which means chapters, subheadings, and book introduction. Very quickly the chapters and subsections where finalised, along with our approach to the examples. I was very keen that the examples where routed in plausible scenarios and that would help the ideas without getting caught up explaining the detail. Not to mention the examples should feel less superficial. Additionally, we have recognised that a book about a cloud solution means that things will move far faster than something that is deployed on-premises, so how we approach this book needs to hold true and relevant even if there are new features and aesthetic changes for a good while.
We divided the work up between us, I think Robert in hindsight took on the more troublesome chapters, in so far needing to understand more social APIs. So when plotting out the division of work, also think about the technical challenges you might have and need to explain. Whilst you won’t have this in perhaps a ‘hello world’ level of functionality when you past this effort builds up, if you’re working on a cookbook it may we’ll be an important factor.
Our original goal had been to publish in time for Open World. But the realities of a job, both of us being active with events such as user groups meant these things would eat into the available writing time as demos, presentations would also need to be written. We also uncovered a couple of bugs that delayed things, both in waiting for the patch, but also confirming that what we where seeing was a bug, and not an issue of understanding.
In hindsight I think perhaps we should have done more work during the planning to build the example scenarios. There is no doubt that planning before actually writing makes a significant difference. It would have given us more time in working through the questions and challenges. The risk would have been that it would have been a lot longer before we actually produced some content, and there is certainly something psychological about getting those initial chapters written.
During the core writing phase Robert and I would gave weekly call to catchup, it meant that we could discuss the chapter scenarios, details, and assumptions that meant we were aligned. Whilst not necessary, and this could be done be email, a short conversation was a lot easier and it helped keep focus. Not to mention probably reduced the differences in writing that can occur with different authors.
When comes to the writing itself I found the clearer my thinking was on the specific points I wanted to convey the easier the writing became and the writing of the chapter just flowed. The question I still haven’t really answered in my own mind is whether I should have been a lot more attentive to the formatting the publishers wanted us to adopt, applying it retrospectively took a couple of passes as you would spot something that had omitted the correct style. But diligently applying the right styles would have been disruptive to the writing style.
We found that most chapters overran the page count by about 10%-15% the publisher was pretty cool about this – they definitely agreed a good book over a book that was edited to a specific length was most important. We can put the over run down largely to the fact we didn’t allow for the formatting of the page, which meant more white space that we had anticipated, plus in the drafts we needed to put additional publication notes in such as references to the images being used. It is worth looking at this before finalising your chapter lengths.
The last thing we did during the writing of the 1st drafts was reviewing each other’s work before submitting the chapters. This probably helped a lot in so far as Robert would often pickup on issues with my screenshots and I would tend to finesse wording – when you write in a more conversational style those little quirks of speaking can come through.
Completing all the chapters in 1st draft felt pretty satisfying, and certainly a morale boost as we had overrun our original estimates, as it meant we where we we’re well over 50% complete, probably nearer to 75% complete in terms of effort. In the contract with Packt this was also the 1st milestone for the advance, which is a long way into the process and the payment has yet to be received. Some of this delay has been organisational, but things don’t happen quickly on that front.
Before we started the project one of the Oracle Ace Directors we knew provided some observations, suggesting that each page will probably take a couple of hours to write. I have to admit to being a little sceptical of this as it would mean roughly a year of writing every evening for both of us if you look at it from an elapsed time it isn’t so far from the truth. If you look at the actual effort, those weeks where I was just working on the book rather than presentations or work demands. I think it would have been fair to suggest about 8-12 hours of effort went into the book each week which is about 450 pages in length. In the end I think we probably where writing at twice that speed if you measure effort from 1st to last draft.
Second draft is about addressing the review feedback from the peer reviewers. For us that was pretty straight forward,the feedback we received was very positive and making suggestions on how to improve things. As we wrote about a cloud product that is developing and improving quickly we needed to double check the screens hadn’t changed. We did see 1 challenge in the reviewing. We wrote the Preface to help provide context to the book, but I didn’t get sent before the 1st chapters went to review some comments as a result perhaps weren’t so intune with the books underpinning goals. Should the reviewer need to have had the preface first, debatable. We took advantage of this lesson, to reduce the dependency on having read the preface.
Most changes where about fixing formatting, then adding a couple of additional screenshots and some clarifying text. Each chapter probably only needed 1 additional paragraph per chapter. So working through this was pretty quick. Then it has been over to the publisher to finishing things off and assemble the book.
Going forward, 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:
We have taken our book on ICS into Packt Publishing’s Alpha programme so that if you order the book now – you can see the chapters as soon as they have received editorial approval and the complete final book will be made available to you as soon as we’re have addressed all the feedback, made any final improvements we have identified once we have completed the book’s draft.
The book can be found on the Packt website – here
Details about the Authors from Packt can be seen at:
- Phil Wilkins
- Robert van Mölken