Writing Is An Undervalued Engineering Skill

Dear new developer,

This post discusses writing and how learning to write well can really level up your engineering experience. You can also view over 300 comments about this post on one of my favorite online communities, Hacker News.

The author has some suggestions on how to become better:

So how can you work on becoming better at writing? Writing clearly, concisely and in a way that is easy to read? As with every skill, it’s a matter of being aware of the fundamentals, practicing, getting feedback and repeating.

I haven’t read the books he suggests for the “fundamentals” (yet), but I agree that practicing, getting feedback and repeating are crucial. It’s why I think that a blog is such a great way to spend your time.

But I think it points to the larger issue, which is that writing well is a scalable way to communicate, and that communication is at important as writing code. If you writing the wrong code, you might as well not have written anything at all.

Worth reading the whole post: Undervalued Software Engineering Skills: Writing Well.



Write a technical ebook

Dear new developer,

I suggest you take some of your ample free time (if you have it) and write a technical book. I’ve written one book and doing so gives you a deep understanding both of the technology you choose to write about and of the difficulties of doing so. It will give you instant credibility should you choose to pursue a job related to the technology. You can use it to make connections and give speeches at meetups.It may even make you some money, but don’t count on that.

Pick a technology that you use at work or on a side project. Characteristics you are looking for:

  • few books have been written about the topic
  • you are really really interested in the topic and want to master it
  • it is something you use regularly
  • the technology is either really new (and you think you might be able to do multiple revisions) like React, or is really old and slow moving (like bash)
  • it’s something relatively popular or new

I made a number of mistakes when I wrote a book about command line hooks in cordova (which is a framework for writing mobile applications). The mistakes I made included:

  • the market for cordova books was small, and the subset of people interested in automation of cordova actions was even smaller (even so, I found about 70 people willing to pay for the book)
  • I picked the technology because we were using it at the time, but after one project we stopped. I wasn’t really interested in mobile development, and so never updated the book.

Topics that aren’t technical are more evergreen (how to manage a software team has changed in the last 20 years, but how to build a javascript application how changed in the last 12 months), but there are more books out there about them as a result. Technical books have a shorter shelf life but also have less competition.

However, if you can find a topic you want to write about, don’t start writing the book from scratch. Instead, outline it and write a number of pieces of the book. An easy way to do this is to create a category on your blog (you have a blog, right?) and start writing regularly about the topic. Write an outline and add blog posts based on the outline.

After four or five blog posts, you’ll know if this is a technology you want to dig into and publish a book about. Keep writing the posts, but start looking for communities where the technology is published. Start answering questions about it on the forum and/or your blog. Set up an email list to capture people who are interested in your topic and visit your blog.

The risk is low. If, on the other hand, you write two articles about technology X and you are bored out of your mind, then just stop and don’t create the ebook.

Once you have about 20 posts, you can start thinking about pulling them together to form an ebook (the exact number depends on the size of your topic). I used leanpub and had a great experience. Note that you’ll be entirely responsible for not only writing the book, but marketing it. However, you get to keep something like 90% of the price of the book. Leanpub can pull an RSS feed into the leanpub format and you can use it to suck down the posts you’ve been writing.

After you do that, it’s really about continuing to fill out the outline, updating your forum posts to include a link to your book site, and marketing the book. I’m no expert there, but made about $700 bucks from my ebook. I don’t think I ever calculated the exact hourly rate, but I can say with confidence that it was far lower than I could have made contracting.

So, in the end, why is it valuable? I think writing a book, even a 40 page ebook like I did, challenges you to think deeply (to understand the technology and convey it in a way that other people can understand) and broadly (similar to holding a really large software system in your mind). These are both really good skills to acquire.



What Mitchell learned in his first two years as a software developer

Dear new developer,

It’s great to see what other developers have learned, especially when they are just starting out.

This is a post covering Mitchell Irvin’s lessons from his first two years as a software developer. Now, I don’t know Mitchell at all (but I guess I am connected to him in the third degree, according to his LinkedIn profile).

But his lessons resonated with me. Here are his lessons:

  • Your relationships with your coworkers (interpersonal/leadership skills) and your technical prowess (hard skills) are equally important
  • Your ability to influence others is most prominently determined by your ability to help them reach the same conclusion you did, on their own
  • It is the mark of a great problem solver to ask many questions before beginning to think about a solution

Each of these is worth a blog post, but I’ll let you click through to see how Mitchell arrived at each of these–some good anecdata.

However, I think that the bigger point is not what Mitchell said, though he has good points. There are two interesting meta points:

  • Mitchell reached me without me knowing him, or knowing anyone who knows him. This is the power of writing, especially a blog. You never know who you’ll connect with.
  • I checked his arguments against my experience and found it resonated. This is a great way to judge new data that comes at you (and, as a software engineer, a lot of information will flood toward you). But you also need to be aware of your innate biases, and think about how the points in any post or article could be false. You also should consider the source. Mitchell has worked at a couple of large companies and his experience may not be applicable at a different type of company.

Being an information consumer and producer is a key part of being a software developer. You should work on your writing to produce information. And you should be thoughtful about your information consumption.



Write that down!

This is a guest blog post from John Obelenus. Enjoy.

Dear new developer,

Even when I was a kid in school I hardly wrote things down. That’s why we had textbooks after all! I was baffled by other students in college furiously transcribing every word that came out of the professor’s mouth. Now I have a career in the world of software where we track everything. Git holds all the code commits, email is never really deleted, and project management and issue tracking tools keep track of what we’re doing and have done. How could anything go missing?

I constantly looking for things and cannot find them. I get a bug report, look at the code and say to myself “That is obviously wrong, let’s fix it.” I look at the offending commit that introduced the bug (of course it was me). But what is not there? The reason for the change. So I look at the project management tool we use. And someone definitely asked for a change, but, I’m still not sure why. So I search through my email for the few days before I made the change, and…nothing. I still cannot really figure out why we all decided to make a change which introduced a bug.

Or, worse yet, someone asks for a change. All well and good. Then a month later, someone asks to change it back. So you shake your head and make the change. Then someone is confused why this is happening, and calls a meeting and invites you to help figure it out. What are you going to bring to this meeting? Did you write anything down? I never used to. Now I do.

Now I have a notepad next to my laptop. And I have a notebook on the shelf. I make better use of git messages and write down who asked for changes. When working on a feature, or a bug, and find something…“interesting” I make a Github wiki entry explaining it. I write a comment in the code base explaining it. There are two kinds of documentation — useful documentation, and redundant documentation.

No doubt many people have told you to comment your code. I hope many people have told you never to comment a loop with // loop over the array. That is not increasing clarity, its just duplicating what the code is doing. Adding noise, not signal. My contention is that comments are rarely useful for explaining “What this code does…” but rather, explains “Because of X, we are going to do…”.

Future you is going to be very happy if you start documenting the intent behind what you’re doing. Good code is easy to read. Bad code is capable of being understood with time. But code doesn’t tell you why you’re doing all this work in the first place. Maybe something has changed and you don’t even need this code anymore — deleting code is the most satisfying feeling. But you won’t know unless you know the intent, the purpose, of the code. And the rest of the folks you’re working with are going to be very happy as well.

If you write everything down (and make it public), they won’t need to tap you on the shoulder when you’re in “The Zone” to ask. When someone wants to set a meeting to understand why things are “The Way They Are” you already captured that information. You can send them the link and kill the meeting (Ok, maybe killing meetings is more satisfying than killing code).

We only have so much time in our life, and we already work long hours. Let’s make future us happier by writing things down, so we don’t have to figure it all out again. We figured it out once when we wrote the code. So capture the knowledge in that moment in time. And Write It Down!


John Obelenus

(Previously published at Medium)

John Obelenus solves problems and saves time through software and crushing entropy



Always Be Journaling

This is a guest blog post from Brooke Kuhlmann. Enjoy.

Dear developer,

Of the many techniques you’ll pick up over the course of your career, one worth investing in early is journaling. Journaling might not seem like a worthy endeavor at first. Capturing important moments of your life on a daily basis might even seem like extra work on top of everything else you are juggling in your life but, in time, journaling will pay dividends if you stay disciplined and detailed. As you grow older, the details of earlier experiences will grow foggy in your mind. Being able to reconstitute past experiences in order to apply to them to present situations will help you make more informed decisions.

Additionally, journaling serves a dual purpose as it makes you a better writer. This is a wonderful skill to have which shouldn’t be underestimated. In addition to technical expertise, being able to express your thoughts succinctly, supported with documented details, is a sought after skill. Inadvertently exercising this part of your mind, on a regular basis, will allow you to keep this skill sharp.


How you organize your journal entries is up to you. Everyone is different and there is no right or wrong way to do this as long as it makes sense, is easy to add new entries, and can be searched through quickly. To start with, journal entries are meant to be chronological, so it does help to use a date/time structure. Example:

Format: <year>/<month>/<day>/<hour>/<minute>/<second>
Example: 2018/12/01/10/10/10

Use of categories (for high level organization) and tags (for associations across categories) can be helpful too. Useful categories to start with could include:

  • Work – Lessons learned from paid work. In addition to the benefits of helping you stay organized and not let important ideas slip through the cracks, this also serves as a way to measure the pulse on how you are feeling about the work you are doing and the progress being made. When you look back over time and see a rocky or downward curve, it might be time to move on to something new. On the other hand, the use of your journal might be motivational, can serve as a reminder to explore previous ideas in greater detail, and can even help solve current problems.
  • Side Projects – Lessons you want to capture related to open source software, hobbies, etc. that might be worth sharing in a public forum at some point but currently is raw material.
  • Personal – For private thoughts and ideas of use only to you. This might include your health, mood, personal reflections, relationships, etc.

As for tags, you might want to use a single tag or multiple tags in order break down journal entries beyond high level categories. Tags make it easier to search for entries faster when, for example, you have a Dotfiles project you’ve been working on and you have it tagged as dotfiles too. Using multiple tags helps connect related journal entries across categories which is another nice way to group related information.

It never hurts to have a few tools to ease this organization of your thoughts. Here are a some recommendations:

  • Bear – Supports macOS, iOS, watchOS. Has great sync capability between desktop and mobile, hybrid Markdown support, and tends to be a more free form in that you can organize and tag information however you see fit. It’s free to get started and $15/year to add pro and sync features.
  • Day One – Support macOS, iOS, and watchOS. Tends to be more specialized for journaling but isn’t always the easiest to manage. It’s free to get started but $35/year for pro features.
  • Notes – Native to macOS and iOS, provides a free solution for gettings started which sync capabilities.


Choose a schedule, for writing journal entries that you are comfortable with. I would recommend at a minimum, to journal daily, even if briefly. It’s up to you to be disciplined about this as as only you will benefit. You can schedule this as a recurring action in your task manager or as a calendar event. Use whatever best fits your workflow and be diligent about it.

In addition to scheduling, you can capture important events as they occur such as thoughts while in a meeting or when working on complex technical issues. Yes, a journal can also be a helpful scratch pad for further reflective and refined thought later. If real-time journaling isn’t sufficient, try scheduling an end-of-day reminder to reflect on the day’s experiences.

Automation, as mentioned earlier, is key to being successful so figure out what works best for your mind and mode of operation. Here are some tools worth adding to your toolbox:

  • OmniFocus – Based on David Allen’s Getting Things Done book. It can cost over $100 when you buy the macOS and iOS versions but syncing is free. It’s a powerful tool and worth the investment.
  • Fantasical – If task managers are not for you, consider investing in a good calendar software and setup recurring events/reminders that way.
  • Reminders – Doesn’t have a lot of bells and whistles but will definitely help get you started until you outgrow it. Free for macOS and iOS.


In order to learn from past mistakes, experiences, and build upon earlier lessons it is important to review and reflect and on your progress. A good rule of thumb is to conduct this kind of “self retrospective” weekly, monthly, and yearly. This’ll help keep where you have been and where you are headed in perspective. Plus, it’s nice to see how far you’ve come or gone off the tracks in case you need to pivot and course correct.

Personal Results

Over the years, maintaining a Pensieve so-to-speak has made me:

  • A stronger writer – As mentioned earlier, since I’ve been journaling, I’ve found I’ve become a much stronger when writing Git commits, responding to group chat responses, creating pull requests, replying to emails, etc. I find my content is structured and well composed rather than short, terse, or staccato.
  • A stronger learner – When capturing and reflecting on the various experiences of your past life you can see connections that weren’t there before. It’s fascinating when I reflect on past work and realize I’ve forgotten a tool or technique that I didn’t fully understand at the time. Now I have much more knowledge and context for how to apply that to the current situation and thus have saved myself additional time.
  • A stronger mentor – When you accumulate a lot of experience and expertise, you can forget what was the source of your tacit knowledge. I’ve found being able to search for and share recorded knowledge so others may learn and grow in a similar manner helps make you a fount of information.

Closing Thoughts

Your future self will thank your past self for recording this history. Being able to understand the long tail of your work — and therefore your life — is valuable in making informed decisions on what actions you’ll take next. Mine this information often because your experiences are gold.



Brooke has been developing software for ~20 years with an emphasis in the Ruby and Elm languages. He lives and works from his home office in Boulder where he enjoys the many bikes paths and close access to ski slopes. When not working on open source software or hanging out with this novelist wife, he can be found speaking at conferences on the Git Rebase Workflow or attending the various local meetups: Boulder Ruby Group, Front Range Elm, or Denver Modern Web.

Start a blog

Dear new developer,

A blog is free (except in terms of time), forces you to think, provides an example of your ability to discuss concepts, and helps others.

What’s not to like?

The hardest part about blogging is just doing it, day in and day out. Now, I am no Fred Wilson, who has blogged every day for 15 years, but I have blogged since 2003. I’ve written at least once every month of those 15 years (except one).

I can tell you that blogging won’t give you a job, but it can occasionally lead to contracts. That it won’t make you a superstar, but can give you credibility. That it won’t make you an excellent writer, but that it will polish your ability to convey thoughts in text.

What should you write about? Write about the latest problem you faced at work the technology that interests you or a comment on a link that you found. It doesn’t really matter as long as you can write about it and can commit.

Because it is the commitment that matters. The benefits of blogging don’t accrue on the first or second post, but on the twenty first or twenty second.

I can’t speak highly enough of blogging. I tell everyone I meet to start a blog. I’m suggesting you do too.