Writing your First Technology Book

So I wrote my first book. It is a great feeling to find your book available on Amazon http://www.amazon.com/OpenShift-Cookbook-Shekhar-Gulati/dp/1783981202/. I have read many motivational books or quotes that suggest everyone should write at least one book in their lifetime even if no one reads it. I hope people will find my book useful and learn from it. This blog is not about my book but it is about the lessons I learnt while writing the book.

  1. Limit book scope: As a first time writer it is very tempting to include a lot of related topics in the book outline. I made this mistake in my book outline but as I started writing the book it became clear that I should drop few topics to write a cohesive book. Pay a lot of attention to the book outline and don’t try to put everything in the book. For example, my book is about OpenShift, a platform as a service that supports Java, Python, Node, Ruby, PHP, and Perl runtimes. In my book outline, I proposed to include everything except Perl and Ruby.  After writing few chapters it became clear that we can’t include everything in one book as it would lead to a book that covers lot of topics but none of the topic would be covered in entirety. Keep in mind book outline will change so always try to keep publisher updated on the same.
  2. Your Estimates will be wrong: The book started with the initial estimate of 250 pages and 6 months writing time. We ended with 430 pages and it took more than 10 months to finish. I suggest you take book writing as another software development project. Like most software development projects, book estimates can also be wrong. The better way to write a book is by taking an iterative approach where you re-estimate after writing each chapter. Consider book writing as an Agile software development project rather than a waterfall project.
  3. Plan your book: I suggest if you wish to write a book on a topic then you should first write a blog series on that topic. I have written close to 70 blogs on OpenShift and that helped me a lot. This not only help in content creation but also gives you an audience that would like to read your book. Make sure to tell the publisher in advance that you would use your blogs.
  4. Managing your time: Writing is a very tedious and time consuming task. Writing a technology book involves various tasks like writing book text, creating sample applications, learning new changes introduced in the topic etc.There would be days when you will be productive and write a lot of content and there will be days when you will not be able to contribute much. Be prepared for lean patches as book writing can tire you more quickly than writing code. Initially I used to write book only on weekends but that didn’t worked for me as my writing flow suffered during the week. I tried writing on weekdays after office hours but that too very quickly became tiring. It is very difficult to write a book with office work. Try to plan few weeks holiday to work on the book. I took a couple of weeks off and only worked on the book. This really helped me finish book and maintain my writing flow.
  5. Read books: As a first time writer there will be times when you will be unsure about a topic or how to correctly convey it to the readers. Reading books can help you learn some tricks or improve your writing style that will help you convey your point better to the readers. Try to steal ideas from good books and apply to your book.
  6. Become comfortable with the book format: I wrote a cookbook that required me to use a predefined template. This sometimes restricts you and slow you down.
  7. Keep all book artifacts in a version control system: I used a private Github repository to store all my book artifacts  including content, images, invoices, source code etc.This not only helps as backup and version control system but also helps to analyze your writing habits. For example, the Github repository contribution graph shown below clearly show my writing flow throughout book writing period.book_contributions_over_timeI also used a separate public Github organization https://github.com/OpenShift-Cookbook for the web applications I developed in the book. This helped me keep all book related application source separate from my own Github account.
  8. Plan for software updates: The biggest problem in writing technology books is that technology changes/deprecates very rapidly. There could be a significant change in the software library that would impact your book quality and correctness.

Hope you find these useful when you write your first book.

How to Write Node.js Applications in Python using PythonJS on OpenShift

Today I came across an interesting library called PythonJS that converts Python to JavaScript. It converts to JavaScript and generates JavaScript, CoffeeScript, and Dart code for the given Python code. In this blog you will learn how you can use PythonJS to deploy Python’s Tornado web framework application to OpenShift’s Node 0.10 cartridge. Read the full blog here https://www.openshift.com/blogs/how-to-write-nodejs-applications-in-python-using-pythonjs-on-openshift

Java EE7 Development and Hosting on OpenShift with Wildfly: Part 1

This is the first blog post in a series where I will cover how to build web applications in Java using Java EE 7. Java EE 7 is the latest release of the Java Enterprise Platform, with a focus on HTML 5 and developer productivity.

Java EE 7 introduced five new specifications covering WebSockets (JSR-356), JSON Processing (JSR-353), Batch Applications (JSR-352), Concurrency Utilities (JSR-236), and Caching (JSR-107). Apart from these new specifications, three existing specifications (JAX-RS 2.0JMS 2.0, and EL 3.0) have major updates and a few other specifications have minor updates. We will cover most of these specifications in detail in this blog post series.

Read full blog here https://www.openshift.com/blogs/java-ee7-development-and-hosting-on-openshift-with-wildfly-part-1

Developing Single Page Web Applications using Java 8, Spark, MongoDB, and AngularJS

In this post you will learn how to use a micro framework called Spark to build a RESTful backend. The RESTful backend is consumed by a single page web application using AngularJS and MongoDB for data storage. I’ll also show you how to run Java 8 on OpenShift. Read the full blog here https://www.openshift.com/blogs/developing-single-page-web-applications-using-java-8-spark-mongodb-and-angularjs

Using Siege for quick and dirty load test — Apache Benchmark Alternative

Today, I wanted to run a quick and dirty load test on one of my applications. One of the alternative that most of the developers are aware of is Apache Benchmark(or ab). For some reason, ab does not work on my mac book because of Connection reset by peer errors. So, I looked around and found Siege. It is very similar to ab and works well on mac.

To test the GET request, you would run

siege http://example.com/rest/todos/3 -c 100 -r 100

To test the POST request, you would run

siege -H 'Content-Type:application/json' "http://example.com/rest/todos POST < ./data.json" -c 10 -r 1000

XWiki on OpenShift

1. Create an OpenShift application using following command
$ rhc app-create xwiki jbosseap –gear large

2. Downloaded the xwiki war file from the official web site.

3. Extracted the war file using $ jar xfv xwiki.war

4. Downloaded three jars — guice-servlet, guice, and h2 from http://mvnrepository.com/ and placed the jars in WEB-INF/lib directory. The application expects these jars but don’t bundle them.

5. Update the hibernate.cfg.xml. Basically, we have commented out hsql and uncommented h2. The NullPointerException that you were seeing was because xwiki does not work with JNDI datasource so you have to bind the url manually. If you want to use postgres or mysql then use proper connection url, username, password etc.

6. Pack the war file again using $jar cfv ROOT.war .

7. Copy the artifact to deployments folder in your app source code. Please delete src/ and pom.xml as you are deploying war file.

8. Git commit and push the war.

9. Check the logs.

Using Python Flask Jinja2 with Mustache

Today I was building a single page web application using Python Flask framework and Backbone.js and faced a problem where Jinja2 was parsing the mustache template. Both Jinja2 and Mustache use {{}} in their templates. When a user makes a first request, I render index.html that contains all my mustache templates as well. The solution to avoid Jinja2 from parsing Mustache templates is to put all the templates inside  {% raw %} and {% endraw %} as shown below.

{% raw %}
<script type="text/template" id="company-template">
	<a href="#companies/{{id}}/jobs" class="list-group-item">
    	<h4 class="list-group-item-heading">{{name}}</h4>
    	<p class="list-group-item-text">{{description}}</p>
  </a>
</script>
{% endraw %}