Valuable things I have learned while writing three books for @PacktPub

I recently had a friend of mine ask me about the viability of writing a book for his open source project. He had questions about how to submit a proposal as well as the money involved. I wrote him a detailed response, but decided to post some of my lessons learned here.

Don’t write a book for the money

This is definitely a worn out expression. I have seen people get this starry gleam in their eye, Sorry, but that only happens when you write a best selling, fictional trade novel. Not everyone can be J.K. Rowling. In fact, there are actually a very small number of authors who make it big. The real name of the game in writing is to write LOTS of books, such that over time, people that like your material end up buying all your titles.

When writing technical books, you still need to sell a bunch to really make any money, but we are forever cursed by books going out-of-date in just a few years. Trade novels last a lot longer.

That may sound a tad depressing. So why write book? Because it can open doors you never knew would happen. When you are a published author, it can impact interviews, speaking engagements, consulting opportunities, and other things. It is always a major +1 to your CV to have written a title. Even more if you get several under your belt. It also increases your overall name recognition and personal brand.

Understand what you’re getting into

Before expending any effort in writing, I made sure we had a contract in place that we both agreed to. I’ve read article where people keep writing chapter after and yet have not signed an agreed upon contract. I don’t work that way. You are taking on risk by doing that. Until a contract is in place, the publisher can bring onboard other writers.

I have historically preferred to write my titles by myself. It lets me control the content 100% and not have to deal with interacting with another author, one who might/might not be as motivated as me. As a nice side effect, it also ensures that I get all the money. Since we’re already talking about a small pile of money, it feels counter production to split it up amongst two or three people.

Packt’s contracts include an option of first refusal for your next two titles. I understand Packt’s desire to get first dibbs on future work. It make business sense, so I had no issue with this in my first two titles. But on the third one, I had decided they had made enough money on me. I asked that this clause be removed to liberate me for future works. I have no hard feelings nor have I felt any malice from anyone at Packt.

Be sure to understand that the contract includes deadlines and exactly how much money you’ll be paid and when. If you sign the contract, you are agreeing to everything stated. Understand what you are agreeing to.

It’s your title. Act accordingly

Every publisher out there will probably tell you how glorious their marketing and sales team is. But for you to write a book and make no mention on Twitter/FaceBook/Google+, nor to write a peep on your blog site is ridiculous. You should be blogging all the time as you write and beyond publishing. Don’t assume that your publisher will automatically sell 1000 copies of your book and be fired up to order another batch!

Another aspect of “acting accordingly” is to remember this will reflect first and foremost on YOU. If you have a certain voice or a style of presentation when you speak at conferences, then by all means, try to write that into your manuscript. Your editors may try to edit that out. If you give them the upper hand, they can reduce your effuse writing into boring humdrum. I’ve seen editors edit out some of my sassy writing. My response? I edit it back in! They don’t usually push back too hard.

It’s important that the publisher have a certain level of quality. But there needs to be enough of YOU in whatever you write that makes it stand out.

Go and read other people’s technical books. Part of this inspiration for me came from a couple other technical books I read. The style these author’s wrote knocked me out of my chair. I LOVED the small jokes, clever class names, and funny material they injected into their writing. And it told me I could do the same, as long as it wasn’t offensive or obnoxious. Again, my editors pushed back, but I paid keen attention to EVERY edit, and undid several of these. I wanted my book to be fun.

Making your book fun is no one’s job but yours.

Take credit for your work – give credit to others

In my latest title, I started each chapter with a quote from twitter. “Spring Boot” was so hot, that I started collecting tweets as I wrote. I would launch a chapter, and include a link to that user’s twitter handle. Their comments were inspirational. I hope they picked up new followers.

At the same time, I gave a presentation that pre-dated release of my book. I mocked up a logo of the book with the title in it, and included that in my profile slide at the beginning. This was a PR moment I wouldn’t pass up. I wanted everyone in that audience to know a book was coming, and hopefully they all bought a copy!

That same week, my colleagues and I trekked to a JUG meeting. Someone in the group asked, “Is there a book on Spring Boot coming?” Everyone turned to me, and I happily gave them the estimated release date. More free PR. I also was sure to cc more than a handful of tweets to that group’s twitter handle. Hopefully they each bought a copy! (Not likely, but one can dream, right?)

Finally, I wrote my last title using asciidoctor thanks to Dan Allen. This was by far the best option. It allowed me to focus on quality content and not idiotic Word Processor issues.

Knuckle down and write

Okay, all these suggestions up to this point are nice and all, but it’s all for naught unless you put in the hours to actually write your book. I read someone’s blog article where they thought the deadlines were crazy since they only planned to write on the weekends.

Sorry, but I don’t have much sympathy there. I wrote each of my books while we also had a newborn baby. I quickly adopted the style of writing every night after everyone had gone to bed. This way, I could focus with no distractions, and then take the weekend off. Writing every night from 10pm-midnight can be exhausting when you mix it with feeding a baby at 2 AM, but this ensured that I got my book finished and out the door. It also cut down on the risk of my technology moving away from me too quickly and making the material invalid, or avoiding massive rewrites due to mega-changes.

Another thing you have to be ready to do is carry your book all by yourself. You can’t depend on certain reviewers to fix things for you. Instead, you need to be ready to proof read in the event your book reviewers don’t actually give you any feedback until the last minute. It’s sad, but this still reflects on you.

There were times when I hit bugs in my sample code, and had to simply pack up for the night. There were other times when I had no choice but to work an extra two hours to hammer out a problem that no one else could help me with, either in my asciidoctor backend, or in my sample code. After all, no one was going to pick this up and fix it, right? Leaning on pull requests, etc. is no excuse for not writing your book.

I demoed Spring Social GItHub in my latest book, and had to go to press using version 1.0.0.BUILD-SNAPSHOT because the project lead was simply too backed up to fix the milestone release already published which broke my book’s sample code. Them’s the breaks.

So by now, if I haven’t smashed your dream of writing a technical book too badly, I wish you only the best in going out, submitting a proposal, and snagging a contract.

GitHub isn’t your CV, and GitHub commits don’t show your talent

I previously wrote about how GitHub isn’t your CV, and went on the even close my LinkedIn profile because of how little value it actually provided.

GitHub’s eye candy

Lately, I noticed people posting things like diagrams of burnout based on a dwindling number of commits to GItHub. Once again, it seems like GitHub likes to invent metrics and measures that seem to me little more than eye candy. Yet I fear managers and engineers using them as hiring metrics.

As my best example of such useless eye candy, I will point out myself. I am a self dubbed editor-at-large for Spring’s Getting Started Guides. The side effect is that if you go check out all the guides, you’ll find my name spread across almost all of them. I can probably claim 80%+ of the commits as well. It makes my GitHub profile look crazy with bursty rates of activity. For a full comparison, compare myself to my colleague Roy Clarkson. GitHub is showing that I have over 2600 commits for the pat year while Roy has 610. I fear that if Roy and I were somehow applying for the same position, someone might use that crazy metric to make a decision!

The truth is, Roy is a project leader for both Spring Mobile and Spring for Android. Roy has tackled countless problems, and being a one-man-band for two projects, has tackled an armada of issues with no one but himself. Passing on him due to a silly metric would be foolish.

The reason I have so many commits under my belt is that I wrote a tiny script that made it easy to roll the guides whenever a new version of Spring Boot comes out. It looks like this:

#!/usr/bin/env python

import os
import re
import sys

if len(sys.argv) < 2:
    print "Usage: %s " % sys.argv[0]
    sys.exit(1)

with open(sys.argv[1]) as input:
    with open(sys.argv[1] + ".new", "w") as output:
        content = input.readlines()

        for line in content:
            if "1.1.9.RELEASE" in line:
                output.write(re.sub("1.1.9.RELEASE", "1.1.10.RELEASE", line))
                pass
            else:
                output.write(line)

os.rename(sys.argv[1]+".new", sys.argv[1])

That 22-line app has saved me hours upon hours of effort and allowed our guides to stay up-to-date with the latest releases of Spring Boot. It’s the reason that when Phil tweets about a newly released version of Spring Boot, I usually tweet about the guides being updated within the hour. My teammates have come to assume my answer to a given problem is, “I can write a script for that.” And this app is nowhere to be found in my GitHub profile.

All code requires context to be properly evaluated

That is the kind of code and context I would carry into an interview. It shows that I know more than one language. I know that not everything is a Java application. It shows that I also understand the dividends paid in saving engineering time. And it shows that I understand the value of keeping documentation up-to-date.

The unfortunate side effect is that GitHub now shows me with MANY days of having bursts of over 50 commits. The thing is, if you were to hire me, there is no guarantee that I would be knocking out 50 commits on key software components. (Unless I write a script that starts doing document updates the same as I do now.)

Hiring others isn’t easy

I have actually hired people in the past. Long ago, when I received my first promotion, my manager explained that I had reached a level where interviewing candidates would be part of my annual evals. I took that on full steam. I interviewed dozens of people. I quickly learned that the one hidden question to ask yourself is, “would I want to work on the same project, side-by-side, with this person?” As can be expected, not everyone was perfect.

But nothing in a resume or any other publicly visible metric tipped me off about the best nor the worst people that worked directly for me. One person took over the mission critical app I had led for years. He had new ideas I would never have thought up. Another was a copy-and-paste developer that couldn’t seem to learn new lessons. He didn’t last six months. There was no way to know this short of actually working with them for a few months.

People, please don’t pick pre-fabricated metrics and eye candy as your criteria to hire and fire. Use real talent and judgment. And be ready to ask yourself, if this person doesn’t work out, what will be your course of action?

One week left for #LearningSpringBoot contest!

3021OS_mockupcover_normalIt’s not too late to join the Learning Spring Boot contest! Spring Boot has made it super simple for people to create new apps rapidly. You still have plenty of time!

I’ve seen a few tweets from contestants. Are you secretly working on an entry? Tweet your github repo, and I’ll DEFINITELY star it so you can score some extra points with the judges.

Just visit the contest site, fork it, create your app, and submit a pull request by January 17th 11:59pm CST (UTC-6).

I’ve already seen cool traffic a la twitter. I would also suggest posting links/announcements at https://www.facebook.com/springsource as well!

Good luck!

Trying to write #JavaScript without Promises? TL;DR Don’t! Using @cujojs when.js instead

danielskullIt’s weird, but I dodged a lot of the web development churn that happened in the late 90s, early 2000 era due to my involvement in thick client, closed source work. Basically, I never worked with JavaScript in the early days. And back then, when I would peek at the source of a website, the stuff I saw was cryptic and appeared unassailable.

Suffice it to say, in recent years, I have gotten real excited about JavaScript. For starters, I have enjoyed its function-oriented nature. If you can get past some of the really cryptic and hard to understand syntax decisions, and only adopt “the good parts”, it’s quite intriguing. I don’t think I could make it 100% my career, but learning more about JS has been quite interesting. And being dubbed “JavaScript Padawan” by some past colleagues was quite endearing.

But one thing I learned real fast was that JavaScript has some sneaky APIs. And by sneaky, I mean that here is async behavior at every turn. I was trying to fix a usage problem with my Spring Data REST demo app (shrink images way down before upload) when I found what clearly appeared to be an async issue. I thought I had found the answer, but Brian Cavalier quickly pointed out that my assumptions were mistaken, and spotted something I would never have realized.  “img.src = /*new image data*/” is an async operation.

Seeing that, I knew what to do. Wrap the subsequent operations in a when.promise, stuff the “return” statement inside a “resolve” operation, and THEN do the img.src assignment.

You see, the only way to really handle asynchronous operations is to embrace Promises, when.js is a killer library for that. It won’t drag in other stuff not needed like some of these universal toolkits. With a Promise-based approach, I have been able to easily build up my snap-a-pic-upload-to-the-server demonstration of Spring Data REST. It really makes things easy to read, and easy to maintain. The first rule about writing software is that you need to be able to come back six months later and understand what you wrote. By breaking up clearly async steps into tiny, chained promises, the results become obvious.

So if you are getting frustrated with JavaScript’s hidden async bits and pieces (after you start using === for equality checking), ask yourself, “Am I using Promises to manage this?”

Kaypro_in_Israel_1984

GitHub offers more ways to develop than I’ve ever seen!

computer_coffeeHave you moved your code base to github in the past year? Earlier than that? Or are you contemplating heading that way.

There are means and opportunities you can’t possibly imagine when you do this. Of course, the immediate benefit is that 100,000s (if not millions) of developers will already be familiar with this platform for sharing code. It’s a great way to look at individual files, pick out lines, create issues, process feedback, and make contributions, all starting with editing a single word in someone’s comment.

But that is just the beginning. With the rise of forking, people can take projects in new directions. Experiment, prototype, throw away ideas that led into dead ends.

On top of that, the people at github invented the concept of organizations. A lot of people start with creating projects in their own personal space. But you can create an independent organization, and use it as the means to coordinate groupings of projects and other things. And get this: a repository isn’t confined to a releasable software project.

3021OS_mockupcover_normalRecently. I published Learning Spring Boot. All the code is available online for free. Naturally I want you to buy my book so I you can learn all the detailed semantics. But for those that have the book, they can grab a nicely distributed copy of the source and not have to type all in by hand.

Then when my editor started discussing some sort of contest where people submit sample projects built with Spring Boot, I realized that github was PERFECT for such an idea. I immediately created the https://github.com/learning-spring-boot organization, put the source code for the book there, and went on to set up a separate repository dedicated to the contest.

With github’s ease of forking and submitting pull requests, I have directed all contestants to fork the contest, code their Spring Boot application entry, and submit it as a pull request. That way, the judges can visit each entry and easily evaluate it. It also provides the means for contestants to tweet their entries, encouraging others to “star” their entries.

And who knows what will come next? If the contest is a success, we can always hold another one. Or whatever else we think of down the road.

The point is, by embracing github, you open the door to an incredible set of possibilities that you can’t even imagine right now.

Cheers!

Announcing #LearningSpringBoot contest! /cc @PacktPub @SpringCentral

3021OS_mockupcover_normalGreetings Spring Boot lovers!

Packt Publishing and I are announcing a contest! Please visit https://github.com/learning-spring-boot/contest to see the official rules, criteria, and deadline to win. We are looking for cool, pithy apps that show of the elegance and power of Spring Boot while also granting you a chance to show off your wild/creative side.

The deadline is January 17th, so you have plenty of time, whether or not you code during the holidays, to dive and create your own work of art.

This contest doesn’t confine you to solving a certain problem or of being a certain size. Instead, we are looking for all sorts of creative ideas on what you think would be cool. But the ability to show off the power of Spring Boot to accomplish it is definitely a plus.

To be über slick, the contest if hosted on github, meaning you simply have to fork the contest’s repository, and convince your friends and teammates to “star” your submission.

And furthermore, tweet it up! By that, I mean get the word out on your blog site, your facebook page, whatever channels you communicate with others on the interwebs. The more stars you can coax out of your lackeys, the better.

Please use #LearningSpringBoot as the hashtag of choice.

I can’t wait to your efforts. (And if you tweet me @gregturn, I will certainly retweet and star any entries I spot!)

Good luck!

UPDATE: Team entries permitted. Rules have been updated to reflect this.

Why I’ve ditched Bootstrap in favor of @inuitcss

 

inuitcssI recently discovered inuitcss and I’ve fallen in love! Why? It’s simple.

No, that’s the answer. It’s simple, as in, inuitcss is simple. So what is it, and what was wrong with Bootstrap?

inuitcss is sassy

What is sass? It’s this CSS templating language. It isn’t overly complex. But the idea is that you can express combinations of CSS patterns using loops, imports, etc., without the final effect being costly. SASS essentially compiles your CSS templates into a single main.css file that you pull into your web page. inuitcss uses sass most effectively.

For starters, inuitcss is broken up in LOTS of tiny modules. That way, you only pull in the modules you are interested in. For example, if you want to create tiny images with text next to them (Facebook status updates anyone?), you grab inuit’s object.media module. It is really small, and hence easy to grok what it does. You want layouts, i.e. dynamic, flexible grids? Grab the object.layout module. Each module is simple and nicely separated from all the other modules. Just pull in what you need. In the end, it makes it easy to slowly but surely, learn what its doing.

I could never figure out Bootstrap did because it was SO BIG and monolithic in size. I just imported everything, buckled my seatbelt, and held on tight.

inuitcss can be as small as you want

Each module has an enable flag. Some, to turn on the whole module. Some modules have multiple sizes. For example, object.buttons has small, large, full, and pill. You enable what you want, and only those parts end up in your final CSS file.

inuitcss has sizing options, and you can pick whether you want CSS classes like desk-1/2 or desk-one-half (or both!).

inuitcss doesn’t impose any design upon you

spring-a-gram-full-width

My app on a desktop

This is the part that really sells things. When using Bootstrap, I had to learn this structure my HTML had to assume. I always hated showing the web layer at presentations, because all that HTML takes up so much screen space. People don’t want me to talk about complex layouts from Bootstrap. So I would always wave it away, pointing out its Bootstrap, and jump to the rendered site. Yech!

inuitcss is simply a bunch of CSS classes. A few have some rules, such as the structure a media object must undertake (like a media element containing a media-img and media-body subelement). But that’s it! Most of inuitcss is how to style components, not how to string them together in the big picture. And for a CSS newbie like me, that is perfect. It makes the task of building a nice looking site not appear ominous. I don’t have to undertake learning all the ins and outs of such complex things as Bootstrap.

By using inuitcss, I was able to style an already built app, and not change gobs of structure! I find that to be a breath of fresh air.

For a pre-alpha release, inuitcss looks really good, especially for responsive!

My app on a tablet

My app on a tablet

One of my tasks was to take my 90’s looking web page and style it for responsive. I really didn’t know what I was doing. But inuitcss made it approachable. I worked with one part of the interface at a time. As I got the hang of its simple classes, I was able to fine tune things. Eventually, I overrode the default colors to plug in my own. I tweaked the line heights (with one setting), and then plugged in a custom font (Ubuntu font family of course!).

Not only did I want styling, I wanted it to work responsively. I had read about the gory details of coding it. I had read a detailed article about em’s, media queries, and other stuff. I figured I was in for a world of hurt given my lack of CSS knowledge.

My app on a phone

My app on a phone

inuitcss made it super simple! They had built in media queries to apply to certain styles and pre-built breakpoints. Basically, you can saw laptop-and-up-1/2, and it parse that as any screen resolution of the tablet device or higher, render with half of the screen width. Or palm-1/3, translating into if-this-is-a-phone-render-with-1/3-of-the-screen. They had one other setting that said to stop floating to the side, and instead stack vertically. I applied that to the palm breakpoint, as you can see right here.

The previous version of inuitcss was a single toolkit. I decided to take the plunge and use the pre-alpha, multi-module, multi-github-repo version. It means that I don’t have access to many of the existing components, like greyboxes. But nonetheless, I have built a sweet demo app for my technology stack that doesn’t suck. And of which, I don’t have to wave my hands because it looks like another Bootstrap cookie cutter project.

I can tell you this: my site certainly looks different (apart from me ripping off the color palette of spring.io).

I’m not going back

In the past, I have commented how Bootstrap makes me look good. While true, inuitcss makes me look wicked! And it seems easier.

I owe so much to @russmiles!

Russ's shipment of Learning Spring Boot, ready to distribute to conference attendees

Russ’s shipment of Learning Spring Boot, ready to distribute to conference attendees

Russ is a good friend of mine I met back in 2008. He was working for SpringSource at the time as a consultant. He had spotted my open source project, Spring Python, and invited me to make it an official Spring Extension. I was quite excited! Along the way, I had this crazy idea of writing a book about it. I had seen so many other Spring books that I wondered if I could do the same.

When I bounced this ridiculous idea off Russ, he immediately told me to go for it. Having written a couple books, he had suggestions on how to pitch it, who might be willing to publish something about what was frankly a niche project, and also brought on board Sylvain. Thus was born Spring Python 1.1.

Throughout the writing process, Russ provided a constant stream of useful feedback and assistance, a veritable mentor by any definition. (The irony being that I’m older!) Fast forward to now. My third technical published, Learning Spring Boot. This time around, I negotiated different options in my contract, I took the liberty of writing it in asciidoctor, and I’ve journaled about the writing the whole time to give potential readers an insight into what they can expect.

When my editor asked about ideas for marketing, I immediately suggested they send Russ a truckload of copies to hand out. He travels to all sorts of conferences. Naturally Russ leaped at the chance. You can see the picture of his shipment at the top of this article.

I have mentioned before that I picked the cover art for Learning Spring Boot to symbolize how the power of Spring Boot is built upon a strong network of roots underneath the forest. In that case, I was speaking about the Spring Framework underneath Spring Boot. Regarding my ability to write, Russ has been a strong foundation for my ever growing reach into the written world. What more can a fellow software geek ask for?

Cheers mate!

“Learning #SpringBoot” is now signed, sealed, and delivered /cc @PacktPub @JavaMUG

3021OS_mockupcover_normalI finally wrapped up edits and proofing the pre-finals. This book is officially completed. The only lingering thing on my plate is migrating the code base into my newly minted github repo. I hope you have already pre-ordered your copy.

According to my editor, they are uploading it to the printers tomorrow. I can’t wait to get my shipment!

I can say this: I’m exhausted. As I write this blog entry, my watch reads 49 minutes past midnight. Nonetheless, I’m glad to have finished such an exciting book. Can’t wait to hold a copy in my hands.

Good night!

I owe so much to the @javaposse. Congrats on 10 fine years!

javaposseYears ago, I discovered the Java Posse. It was a phenomenal podcast. Every episode was chockful of deep technical discussions, modern issues and revelations in the Java community, and just good old fashioned fun. I thirsted for every episode.

These gentlemen were technical experts who also had loads of real world experience. They pointed me to new technologies, emerging technologies, and fostered my desire to start read blog sites. Back then, I had discovered Google Reader and slowly accrued over 100 blog sites to monitor. All of this constant reading and digesting, along with links from the Posse themselves has made me a better developer.

If I had relied on the dusty books on my shelf, my skills would never be where they are today. By constantly growing and polishing my skill sets beyond what my job demands, I also grew a hunger that I realized couldn’t be satisfied at my old company.

When my wife discussed changing jobs so we could relocate, I had been encouraged to be bold. Asking myself, “where do I REALLY want to work?” The answer I immediately felt: “SpringSource”. I made it a goal of mine. It took patience, but a year later, I was presented an offer. And here I am.

Reading just today on twitter that people were attending the final episode struck me very strongly. I knew it wouldn’t last forever. In the past couple of years, their subject material was shifting away from Java and into other areas. That was natural, because the members had moved into other areas of the vast Java community.

In the end, ten years of podcasting is an incredible story. Congratulations Dick, Tor, Joe, Carl, and Chet! Your production has touched more people than you can possible imagine.