Several months have passed since The Programmer’s Black Book was officially published, after a year and a half of work on the project. Since then, I’ve received many comments, fortunately most of them positive (though some were less so). Overall, they make me think that software developers complain about much the same things wherever we work (Chile, Venezuela, Brazil, Spain, the U.S., and so on), and that the corporate world’s understanding of software development is quite similar almost everywhere. The larger a company is, and the more its name sounds like “IT Services Consulting,” the more the craftsmanship of the work gets lost, unfortunately.
We always learn something from a project, sometimes a great deal; it all depends on the attitude we bring to it. Even if we repeat the same kind of project, we can always find better ways of doing things. So whether we learn and improve—and how much—depends directly on our attitude.
We only improve if we’re internally motivated to do so. No one—not our boss, our colleagues, or our company—can make us grow professionally unless we’re already open to it.
I believe the greatest value we can bring to our organization is to maintain a continuous attitude of learning and adaptation. Human resources departments should recognize and take that into account.
As I shaped the book, I wrote down many gems of wisdom I wanted to share. At the same time, some ideas settled in my mind while I explored others more deeply. Writing a book is a lesson in humility in itself, and every chapter puts you to the test.
I always tried to stay engaged and listen whenever I posted an advance copy of a chapter on the website. There’s nothing worse than thinking you have the last word and are absolutely right. This somewhat ego-driven (but not selfish) attitude blocks us from discovering new possibilities and, above all, from noticing our own mistakes. The encouraging comments, the reports of typos, and sometimes the scathing anonymous criticism all helped me greatly improve the content and quality of most of the book’s chapters.
Likewise, you soon discover that discussing certain subjects—such as the chapter called “When the Project Manager Is Their Own Worst Enemy”—can make former acquaintances uncomfortable or even confused. You quickly learn that you can’t please everyone (a great lesson, in case you haven’t learned it yet). If the book is meant to improve certain negative, recurring aspects of our profession, then of course I have to point them out to suggest a remedy! And for the record, I’m the first to have made almost every typical mistake mentioned in the book, so I’m a great first-rate example…
Sometimes, avoiding making certain people uncomfortable holds us back from starting projects, improving how our department works, and so on. Ironically, those people who get in the way sometimes aren’t even people we like… The lesson: don’t let the possibility that some part of your work may upset or stir up bad feelings in certain people stop you. Fortunately, this is quite unusual.
Thinking you know something, or have some ideas about a subject, isn’t the same as trying to put those ideas into writing and convey them to others clearly, simply, and engagingly. They’re completely different kinds of thinking. So if we really want to master something, there’s no better way than to spend some of our time teaching it.
Writing a book on any subject forces you to question everything you believe, simply because you have to justify and argue for it. You also have to earn credibility from the very first line by citing references and experience, avoiding contradictions, and maintaining a consistent thread throughout. There’s nothing worse than a software development book about technology X where you can tell the author has completed very few projects using it.
Here’s the next lesson: if you want to write credibly about something and earn people’s attention, you need demonstrable authority on the subject and as much expertise as possible. The more expert you are, the more attention and followers you’ll gain. Having our own blog where we occasionally publish tutorials, short articles, and so on about the subjects that interest us isn’t just good—it’s an excellent idea. In fact, it should be a common, almost obligatory practice among company employees, helping maintain a spirit of progress in the work we do.
Writing as part of a project that lasts more than a year takes a lot of discipline (an enormous amount of tenacity), and you have to endure periods when the rest of your activities leave you exhausted, as well as others when you’re completely blocked and can’t make progress on certain topics. If you can’t maintain a routine for a long-term task, forget about trying to write a book.
The Programmer’s Black Book took shape at night (after my two daughters had gone to bed…), on weekends when I had enough free time to focus on a subject for more than two hours straight, and, of course, during holidays, taking time away from my family and the other things I do outside my full-time job. That’s why I say it takes discipline more than hard work: the ability to keep going month after month, even when you’ve been stuck on a particular subject for a while.
Whether that extra effort is worthwhile is a very different question, with many sides and angles to consider.
It’s also a matter of methodology: whatever kind of work we’re doing, if we stop for a moment, take a step back, and try to plan and organize it—even minimally—we’ll get better results in less time. That’s productivity, plain and simple.
For the book, I came up with a writing and revision process for each chapter that went roughly like this:
- Outline the chapter’s main ideas.
- Develop the first draft.
- Thoroughly review the draft.
- Publish an excerpt on the website as a preview.
- Digest and analyze the feedback (curiously, many comments came by email through the contact form, rather than as comments on the website).
- Develop a second draft.
- Review it again and mark it as finished.
- Read it yet again, and if anything still didn’t feel right, revise it once more.
Several weeks could pass between the first step and the last, so I often worked on several chapters at the same time. This leads to what I think is a very important lesson: if we’re working on a project that isn’t our full-time occupation and will take a long time, we have to organize it somehow, deciding how and what steps to take at each point—in other words, we need some kind of plan and methodology.
At first, I made a basic outline of the subjects I wanted to work on, drawing on personal writing I’d been doing for several years. After making a list of around fifty topics, many ended up being covered across several chapters, some were discarded, and others—despite having been written—didn’t make the final book, either because they were too long, didn’t meet the minimum quality I expected of myself, or didn’t fit coherently with the rest of the book.
Another very important lesson for me: know how to let go of something you’ve worked on, even if you’ve spent many hours on it. It reminds me of how much effort it can take to remove part of a software solution that’s become obsolete, is never executed, or should be replaced because we’ve found a better way to solve the problem.
For any personal project, it’s important to set a final deadline. Setting one is pointless unless we commit to it. That commitment to ourselves acts as a springboard: it forces us to find strength during low points and to step on the gas as the month we planned to finish approaches. There’s nothing worse than disappointing yourself, strange as that may sound.
Our self-esteem is tied to the strength of the commitments we keep. As I sometimes argue in the book, the foundation of building software to the highest possible standard is that personal obsession with perfectionism and doing things well. Writing software isn’t just a technical matter.
Although I’ve spent years writing personally about many subjects, I’d never reached the point of having a structured work ready to be edited as a complete book. That was one of my mistakes: leaving the editing until the end. It would have been much more efficient, and saved me many hours of work, if I’d dealt with editing issues as I developed the book. I didn’t have a professional editor, although a good friend from Galicia helped me review the chapters bit by bit. He spotted typos everywhere, and I’m very grateful to him (I gave him a copy of the book when it was published, and I still owe him many beers).
Another great lesson: share your work as much as you can, and accept all criticism, whether it’s right or wrong, whether you like it or not. It improves the quality of the work in several ways. I wonder why we take criticism of our work so badly. We should learn to see that some criticism contains an improvement that can benefit us. That’s different from the madness of criticizing just for the sake of it…
Editing a book isn’t just about correcting grammatical and spelling errors; it’s also about giving the topics and chapters a coherent structure, which is even harder. Readers should move through the chapters as if climbing a staircase, without having to go back and without missing a step on the way to the top. I spent a tremendous amount of time on this once I’d finished all the chapters. Now I think it would have been more effective to do that work during the year and a half I spent writing them.
On the technical side, I realized too late that formatting the book’s content in Word was not merely a bad decision, but a terrible, disastrous one, even though I’d read recommendations about this on numerous blogs. Even with the latest version of the tool, I suffered several catastrophic crashes that cost me some sections.
Because of that mistake, I had to spend a great deal of time formatting the entire book with the wonderful Sigil tool to produce a sufficiently polished EPUB edition. From there, I could have generated the PDF needed to upload and validate it through CreateSpace according to that platform’s specifications. If you want to publish in EPUB / MOBI and also need a PDF (the format most self-publishing platforms usually require), after all my work on The Programmer’s Black Book, I’d recommend an orderly workflow along these lines:
- Write the chapters in raw form (roughly, without worrying about formatting), using any tool. The important thing is not to leave ideas undeveloped; there’ll be plenty of time to review and improve the content many times later.
- Set aside time to move completed, reviewed chapters into a tool such as Sigil, and establish the right formatting based on the publishing platform’s recommendations.
- When everything is finished, generate the PDF using PDFCreator, for example.
Simple and efficient. As for formatting, there’s no need to reinvent the wheel: follow the best practices recommended by the platform where you’ll publish, or by your editor if you’re working with a traditional publisher.
One lesson here is to set aside separate blocks of time for writing—to clarify your ideas—and for editing and formatting the content. If you try to do everything at once, the work you write and the ideas you want to convey will lose depth. For example, if you’re writing about code refactoring, forget about indentation, italics, paragraph spacing, and so on for the moment. Leave that work for another time.
When it came to publishing, I spent some time wondering whether to approach one of those traditional publishing companies, but I soon lost heart after seeing and reading the same arguments against them on many blogs:
- Extremely long response times, sometimes more than a year.
- Given the limited tradition of technical software publishing (at least in Spain), I couldn’t find a publisher in my country that I thought would be interested in publishing a book as eclectic as The Programmer’s Black Book. There are publishers, yes, but they tend to publish English-language translations. Maybe I’m wrong and a publisher would have been interested—who knows?
- Punitive royalty terms. Some publishers even charge you to review your own book, whether they publish it or not…
- And, of course, it’s the twenty-first century, and although Amazon can be a controversial company, I love it…
I discovered that Amazon had acquired a self-publishing company called CreateSpace some time earlier. When I saw the tools they offered for reviewing the work, the terms, the much better royalty rates, the book’s minimum final prices, and the connection to Kindle publishing, I had no more doubts. From then on, I knew which platform I’d use and how I’d publish both the print and electronic editions.
One thing that finally convinced me was that on another popular Spanish platform I’d tried, the minimum retail price for a paperback was €18, while CreateSpace let me price it at what it costs now (€10). That seemed more than reasonable for a personal project, and made it affordable to anyone.
No self-publishing platform is perfect, but the combination of Amazon KDP and CreateSpace seemed best suited to the work I had in front of me. That said, you need quite a lot of experience using web tools. If all you know how to do on a computer is browse the Internet, my advice is to hire someone to handle the publishing process for you.
As I argue in one of the book’s chapters, a client needs to perceive that what you deliver is good. It has to be good, but it also has to look good. So I didn’t hesitate to hire a talented designer I know to propose the cover, back cover, and interior illustrations. After a few drafts, I was delighted with the cover. In my opinion, it captures and subtly hints at the book’s content, in a way that speaks to software developers.
Here’s another lesson: forget about doing everything yourself. Unless you’re a good designer, it’s much better to hire a professional who’ll do a far better job. You can also work with a professional editor to thoroughly review your text.
Before marking the book ready to print, I ordered two physical proofs.
When the first copy of your book arrives with your name printed on it, the feeling isn’t just great—it’s wonderful and exciting. At last, all that effort has become something physical.
When the first proof arrived, I learned another great lesson: reading on paper helps you notice small grammatical flaws and details of expression. At least that’s true for me. Maybe we read faster and focus less on the text on a screen; I honestly don’t know. The point is that although I’d already considered the book finished, reviewing the first printed proof revealed many flaws and things that didn’t feel right to me. I had to delay publication by several more weeks, read the whole text twice more, make corrections, upload it again, and order another physical proof—all while taking time away from sleep and important appointments at work, and so on. A second intense, detailed read of the printed proof finally put my mind at ease, and at last the time came to click the CreateSpace publish button.
And sure enough, two days later you could search for the book’s title on any Amazon site and find it there, with its synopsis, the right price, and so on.
Personally, the best thing about a project like this isn’t seeing your name on a publication that attracts some interest from your professional peers. It’s having kept a personal project alive for a year and a half, having had enough tenacity to shape it, and finally publishing it to a fairly high standard. Most entrepreneurial projects fail for lack of tenacity.
Some people may think writing a book will add a certain prestige to their résumé; “author of…” doesn’t look bad, even if it sounds a little childish. If that’s your main motivation for writing, or if you write like a mercenary just to earn money, the book will lack the passion and interest needed to engage readers. You can only write well about something if the subjects you cover matter deeply to you.
The growing sales of The Programmer’s Black Book make me think that people are very interested in it, and that it’s genuinely adding value for the developers who buy it.
My current full-time work at Telecontrol STM has also been greatly enriched by implementing and putting into practice all the methodologies and proposals that help us do the highest-quality work possible and, above all, work productively.
I always say that what enriches your day-to-day work for a company most is your own personal projects, because they give you a chance to explore paths whose value you eventually bring into your daily work, benefiting both you and the company you work for. Some well-known companies do this by allowing employees to spend some of their working hours on personal projects and ideas, knowing that this motivates and inspires employees and can also lead to important business ideas.
Would I recommend that others write a book of some kind?
Not at all. I only recommend that we learn to identify what we enjoy and feel passionate about, and discover where our talent lies—in the things that make time disappear when we’re doing them. That might mean writing a book, cultivating a Zen garden (I still don’t know what that is), or spray-painting the neighbor’s wall. The ultimate achievement is being able to make a living from the very thing you’re especially talented at.