How to start blogging

Dear new developer,

I was asked about how to start blogging during the Q&A portion of a talk I gave. I had offhandedly recommended blogging as a great way to make connections and to be both credible and findable (locatable?) when looking for a job.

I started to spout off an answer using WordPress, and the questioner said “what about medium?”. And I stopped short. The correct answer is was “whatever is easiest”. I realized that this needed a bit more explanation, hence this letter.

So, the first thing to realize is that almost no one will read it, especially at the beginning. Why would you write if no one will read it? Well, to clarify your thought, to provide a written record of what you’ve done, and because, if you keep at it, Google will find it. Google is great at the long tail, so if you write something that is of interest to anyone, eventually people will find it.

Some numbers. This blog had the following stats for the first six months:

  • Sep: 8 posts/5 visitors
  • Oct: 11 posts/20 visitors
  • Nov: 6/15
  • Dec: 9/219
  • Jan: 8/221
  • Feb: 9/223

For the first month, I wrote more posts than visitors! And for the first three months, I had 25 posts and only 40 visitors. If you aren’t ready and willing to commit for a fair bit of time, your blog will become one of those sad blogs that I occasionally run across with three great posts, then one post six months later with the title “I haven’t posted in a while…” and then nothing.

Now, if that’s what you want, that’s ok (everyone can blog for their own reasons) but if you are looking for credibility and locatability, well, that kind of blog accomplishes neither.

So, commit for six months. I do this by:

  • writing out 20-30 titles of blog posts I want to write. If I can’t come up with that many blog post titles, I am not passionate enough about the topic to stick with it. Better to find out before investing the effort.
  • Watch for interesting concepts and mailing myself whenever I have a possible blog post idea. Then I can search my email when I have time to write but no ideas. (You can do the same with a spreadsheet, doc, trello board or whatever. Just capture the inspiration when you can.)
  • Make some posts easy by doing excerpts or commentary (about half of the posts on this blog are excerpts or guest posts).
  • Settle on a consistent schedule. No need to announce it, though. (Some people do it daily, for which I have mad respect.)
  • Write blog posts ahead of time and schedule them out. When the muse is present, it can be easy to jam out a few posts. When the muse is absent, it is a relief to not need write, but still be able to deliver to previously mentioned consistent schedule.
  • Realize that some of the posts will be mediocre. It is embarrassing to put out poor content. Don’t do that, but some posts will be better than others. Volume is key, and the longer you do it, the better the posts will get.

As far as the actual writing tool, use whatever is comfortable and easy. That may be wordpress.com, may be medium, may be netlify + hugo. Whatever it is, don’t let the technology get in the way of the writing. Especially if you are a developer, it can be more fun to be in weeds tweaking your blog deployment pipeline (at least, that’s really fun for me) but that will distract you from the main goal, which is to create good content.

My final tip is to share on online communities. Don’t only share your own work, but definitely share it. Which community? Well, find out where your people are. There are a lot of communities out there, whether tech specific like Hacker News, general purpose and public like Twitter, or focused and private, like the HangOps Slack. (Sharing is how I was able to break through in December above.)

Doesn’t matter what it is, as long as you are engaged in the community and the topic of your blog is of interest to the community. These communities are well aware of the traffic they can bring and are often wary of newcomers. I have gotten a few scoldings when I posted things that I thought were interesting, but were not in line with the community. That’s OK, just accept the community judgement, acknowledge the mistake, and do better.

Blogging is a great way to amplify your voice, display your expertise and share your knowledge. Set yourself up for success when you start one.

Sincerely,

Dan

Things learned from a senior developer

Dear new developer,

This post by a Bloomberg developer catalogs everything they learned sitting next to a senior developer for a year. Lots of good stuff in there. Favorite excerpts:

How to handle an outage:

For when things go wrong, and they will, the golden rule is minimizing client impact.

My natural tendency when things went wrong were to fix the problems. Turns out, it’s not the most optimal solution.

Instead of fixing what went wrong, even if it’s a “one line change”, the first thing to do is rollback. Go back to the previous working state. This is the quickest way to get clients back on a working version.

Only then should I look at what went wrong and fix those bugs.

This is really good advice. When you are under pressure in a production outage, the tendency to try to figure out what is going on can be very powerful. However, figuring out the root cause of the issue is probably not as important as restoring functionality to your end users. Roll back. If you won’t be able to replicate the issue in your staging environment (due to load or some other reason) save off your logfiles and note the start and end times of the outage for further analysis (slack is good for that).

On code reviews:

Code reviews are amazing for learning. It’s an external feedback loop on how you’d write code vs how they write it. What’s the diff? Is one way better than the other? I asked myself this question with every code review I did: “Why did they do it this way?”. Whenever I couldn’t find a suitable answer, I’d go talk to them.

After the first month, I started catching mistakes in my teammates codes (just like they were doing for mine). This was insane. Peer reviews became a lot more fun for me – it was a game I looked forward to – a game to improve my code-sense.

My heuristic: Don’t approve code till I understand how it works.

Code review is definitely a skill worth practicing. You don’t want to nitpick and I’m a fan of automated linters/code style enforcers. That way you can have all the ‘where does the brace go’ arguments once, and then have the rules automatically enforced. Of course you can look for bad variable and function names, and that is valuable (and non automatable). But in my mind there are two aspects code review that are harder, but more important:

  • How does this fit into the overall system. Are there other components that should use this code or be used by this code? Is this structured correctly?
  • Do I understand this code and what it is trying to do. This means you need to understand the problem that the code is solving.

The whole thing is worth a read.

Sincerely,

Dan

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.

Sincerely,

Dan

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.

Sincerely,

Dan

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.

Sincerely,

Dan

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!

Sincerely,

John Obelenus

(Previously published at Medium)

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

 

J

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.

Organization

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.

Schedule

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.

Reviews

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.

Sincerely,

Brooke

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.