Asynchronous —You can write a question at 8 a.m. and someone can read it and give you an answer at 5 p.m.
Shareable —If knowledge is written, you can share it with others easily.
Clarifying —Whether I am documenting for others or for myself, it’s easy for me to say or think something vague or unclear. But when I write it down, the uncertainty or doublethink is easier to detect.
Durable —When you write, the resulting document can exist for years, if not decades. When someone else needs to understand what you learned, they can get an answer even if you are not available.
Of course, writing isn’t just for sharing knowledge. It’s also for discussion, explanation, and connection. Writing is an underappreciated engineering skill, and you’ll be a better developer for practicing it.
Read your work aloud
Dear new developer,
One of the best ways to improve your writing is to read it. Doing so will help you edit and refine your text. But speaking the words aloud helps more than a silent reread.
For some reason, when I am silently reading something I’ve written, I skip over awkward phrases or misplaced words. This is especially true if I’ve been working on a document for a while.
But reading the words aloud doesn’t just help with typos and awkwardness. It will also help you notice the cadence and word choice. Are there run-on sentences, with three or four clauses strung together? Do! You! Overuse! Exclamation points? Have you used the same word three times in the last paragraph? Do you use jargon or acronyms when simpler terms would suffice?
I find all these flaws easier to gloss over when I am reading a document silently. Don’t trust me? Read this next sentence silently and then aloud:
This a is a simple sentence.
When I scan that sentence, I skip over the typo. Did you? I notice it when I read the sentence aloud. Speaking written text forces you to slow down. In my experience, the denser and more complex the concepts in my writing, the easier it is to skip over errors and awkwardness when reading it silently.
I read my work out loud whenever I can, before submitting a post or sending an email, because the process improves the end product. I have spoken every word on every page of this book.
It does take longer, so I sometimes don’t have time; I also won’t do it with quick emails—I don’t read “yes, that works” out loud when replying to a scheduling request. But many emails and chat messages benefit from being read aloud, and all longer-lived documentation does as well.
Give it a try.
Sincerely,
Dan
Write that down!
John Obelenus solves problems and saves time through software and crushing entropy.
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 am 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 can’t 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. 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 I finding something “interesting,” I make a GitHub wiki entry explaining it. I write a comment in the codebase 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, it is 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 are far more useful when explaining “Because of X, we are going to do….”
The 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 will have already captured that information. You can send them the link and kill the meeting (okay, 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. Capture the knowledge in that moment in time. And write it down!
Sincerely,
John Obelenus
Tips for using email well
Dear new developer,
For all the hullabaloo about chat systems like Slack and Microsoft Teams, email still rules the roost when it comes to cross-organization communication. It is the baseline across every business I’ve worked in.
Everyone has an email address. Email communication is auditable. And it’s immutable after it has been sent, to the chagrin of anyone who has ever hit send and wished immediately they could call the message back. If you want to communicate with a vendor or candidate, you don’t have to get them access to your chat system. To send an email to anyone in the world, you only need to know the recipient’s email address.
Email is often an organization's permanent record of documentation and decisions. Chat systems also try to provide this, but email is prevalent. I remember one founder had a Gmail account that dated back to the start of the company. He would sometimes pull up and forward email chains from years back as they became relevant again.
Email is great at conveying information, but awful at conveying context. A poorly written email can be puzzling. Because email is asynchronous, this can cause slowdowns and confusion, whereas the same lack of clarity in a real-time conversation is addressed in the moment. For example, when someone uses the word “tomorrow” and today is Friday, you can ask “when you said tomorrow, do you mean Saturday or Monday, the next business day?”
Keep an email as short as possible. Many people are reading or responding to email on their phone, and overly long emails can be unpleasant.
If your email must be long, add an executive summary at the top. If you are asking for a decision, make that clear and then provide the context further below. It doesn’t have to be fancy: “I think we should upgrade our PostgreSQL database. What’s your opinion? More details below.” works great.
If it is a sensitive topic, are you sure you want to use email? Consider a face-to-face or other high bandwidth conversations instead and then write up an email to capture the context and any decisions made. If the other party has a differing understanding, get back into the meeting room, on the phone, or into a video call.
Email chains are hard to follow. Add links to supporting documents rather than attaching them. Consider taking the content from a long email and putting it into a document.
Avoid using relative time references. Because email is asynchronous, you never know when your email will be read. An example of a poor time reference: “We’re upgrading our PostgreSQL database tomorrow.” When exactly is “tomorrow”? “We’re upgrading our PostgreSQL database on Thur Mar 26” is far better. Bonus points for adding the timezone: “We’re upgrading our PostgreSQL database on Thur Mar 26 at 5pm Mountain Standard Time” has no ambiguity at all.
Keep your emails focused. A laundry list of questions or issues is fine, as long as they all relate. Email threads which change topics over time lead to confusion. You aren’t paying by the subject line, so use a new one.
Email is a powerful mode of communication. Make sure you use it well.
Sincerely,
Dan
Real-time messaging
Dear new developer,
Chat systems , like Slack and Microsoft Teams, are common ways for developers to communicate. These real-time messaging systems are asynchronous but can be conversational if both parties are present. You can cut and paste with ease, making them a great way to share technical troubleshooting information. They provide a written record of discussions with timestamps. And they can be integrated with other systems like monitoring and alerting to provide historical context for actions.
Default to public—One of the benefits of using chat is that it is searchable. If you ask a question about a system component, later on someone can search for it. They’ll either find the answer or see that the question wasn’t answered, also a signal. But if you aren’t having chats in public channels, the future searcher can’t find it. It can be scary to put your ignorance out there with a public query, but it is better for the organization in the long term to default to public communication.
Use higher bandwidth options for sensitive conversations—Chat is flat. Even with gifs and emojis, it doesn’t have the emotional depth of a phone call. If you want to discuss something fraught with feeling, do it in person, over a video call, or using the phone, in that order. Performance discussions, for example, can lead to misunderstandings and hurt if conducted over chat. If a conversation appears to be heading toward sensitive topics, it’s okay to say “hey, can we go to video?”
Consider other forms of communication when chat runs long—Much the same as the previous point, if you are troubleshooting a technical issue, it’s often much quicker to hop on a screen share or walk over and talk in person. Don’t be afraid to use chat to start a conversation but finish it in other ways.
Follow up with chat—Summing up a discussion with a chat has the same benefits as a summary email. Such a chat review makes sure everyone agrees what was decided and records it for future reference.
Set boundaries—Responding to chats feels like accomplishing real work. And it is, as communication is a key part of software development. But set your boundaries and communicate them. I turn off notifications as soon as I install Slack because I want to view the messages on my schedule, not whenever I get a “ding.” I also don’t install Slack on my phone because in the past I’ve checked my work Slack messages after hours, which didn’t feel great. Discuss appropriate boundaries around chat communication with your team.
Slack and other chat systems have unique benefits, but their intrusive communication methods and lack of context mean that you can’t treat them as equivalent to other forms of written communication.
Sincerely,
Dan
Write a technical ebook
Dear new developer,
I suggest you take some free time and write a technical ebook . Doing so will give you a deep understanding of what you write about. It will also give you credibility. You can use the writing process to make connections and give talks at meetups. An ebook may even make you some money—but don’t count on that.
Only a few books have been written about it.
You are interested in the subject and want to deeply learn it.
You use it regularly.
The technology is either new and dynamic, like React, and you’re excited to keep the book up to date, or it is old and static, like bash.
It is relatively popular.
The market for Cordova books was small, and the subset of people interested in automation of Cordova projects was even smaller.
I picked the technology because my employer was using it, but after one project, we stopped. I wasn’t really interested in mobile development so I never updated the book. That meant it quickly became out of date.
Topics that aren’t about a particular technology have a longer shelf life. How to manage a software team has changed some in the last 20 years, but how to build a large-scale JavaScript application has changed in the last 12 months.
When you select a topic, don’t jump right into drafting the book. Instead, outline it and write sections of the book over time. An easy way to do this is to create a category on your blog (you do have a blog, right?) and post regularly about it.
Writing the book in sections is low risk. If you write two posts about the technology and you are bored out of your mind, stop. After four or five posts, you’ll know this is a topic to which you want to commit. Now, start looking for communities where the technology is discussed. Answer questions and respond to discussions. If a question is especially interesting or brought up frequently, write a post to answer it and share that. Set up an email list on your blog to capture visitors who want to be kept up to date with your posts. You can then market to this engaged audience when your book is published.
Once you have about 20 posts, start pulling them together to form an ebook . After you start writing the ebook, include a link to your book site in the signature of any community posting you do to help market the book. I used Leanpub2 and had a great experience—you get a free book website, and they handle payments and publishing in various formats. With this choice, you are responsible for not just writing the book, but marketing it. However, you get to keep the lion’s share of the revenue.
You can also contact a publisher and see if they’d be interested in your book. They’ll take more of each dollar of revenue, but will provide editing, marketing, and other services. They also have credibility with readers. For a niche book like the one I wrote, the market was so small that I don’t think a publisher would have been interested. Of course, that might have been good information for me to know, too.
I made about $700 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 writing code.
So, why is writing an ebook a valuable use of your time?
Not for the money.
For the glory? Perhaps. It's possible your book will open some doors.
But really, I recommend it because the ability to persist in creating a large, complex product based on research and understanding is a foundational aspect of successful software product delivery. In other words, writing an ebook and launching a software system are similar. Writing a book also challenges you to think deeply and broadly. You must think deeply to understand the technology and write about it in a way other people can understand . And you must think broadly to create a cohesive whole. This is similar to holding a complex software system in your mind.
Sincerely,
Dan
On developer documentation
Dear new developer,
I love documentation . I like writing it, and when it’s well written, I love reading it. There are many types of documentation, and they aren’t all the same. Some illustrate what you can do with a consumer product. Some nail down exactly what will be accomplished between two business parties. But what I’m writing about in this letter is software documentation for developers.
Good documentation of this type cuts down on communication between software engineers, increasing team scalability. At a former company, each developer had a copy of the application server to develop against. Every time a new developer rolled on to the project, this environment had to be set up. Either the new developer had to do it, or someone else did.
I was involved in setting up the first one or two instances, but I got tired of that task quickly. I wrote a step-by-step onboarding document which enabled incoming developers to do the setup themselves. This was good for me, as it saved me time, good for the new team member as it gave them a greater understanding of the platform on which they were developing, and good for the project, as if I got hit by a bus, the knowledge of how to set up a development environment wasn’t lost.
Documentation has come to my rescue more than once. It often captures information that I or others struggled to find. We may need this information but use it infrequently. For example, I once imported a project I was working on into Eclipse, a Java IDE. It wasn’t a cakewalk. I wrote down how I did this, but a few months later, I couldn’t have told you the first thing about it. That knowledge had been evicted from my brain. But, should I have a need to do another import, I can! The knowledge is stored safely in text.
// We convert from Central timezone to UTC here, using the standard library.
// This module exists because we had to integrate with the Acme data feed. They store timestamps in the Central timezone, which is why we do the conversion here.
I’ll take the second comment all day long, thanks. It gives me context, and I can ask teammates about the Acme data feed if I need more. Names of classes, functions, and variables are great ways to document intent as well, and these have the virtue of being harder to neglect. Yes, you can change the logic without changing the name of a method, but developers are more likely to modify that name than they are to update the comments, in my experience.
Documentation is a great way to get started in open source as well. Many projects have working code, but minimal docs. But such documentation is important in helping engineers unfamiliar with the project get started. Look in the issue tracker of your favorite open source project and see if any documentation needs to be written or updated. Even fixing a typo or clarifying a confusing sentence makes the project better. It’s a great way to "give back" to open source projects you are passionate about.
There are two objections to developer focused documentation that I’d like to address.
One is that it quickly becomes outdated. This is true. It takes effort to maintain documentation. When I change a process or system attribute that requires updating docs, I remind myself of the benefits mentioned earlier. If I can convince myself that I will save more time in the long run by documenting because I won’t have to explain the changes to others or myself, then I do it. I’m not always successful, I’ll admit.
Out-of-date documentation can be very frustrating. You can either remove the documentation or loudly mark it “OUT OF DATE” if it will illuminate past decisions. Either way, help people avoid archaic developer documentation.
The other issue is what I call the “protecting your job” excuse for avoiding documentation. If you don’t document what you’ve done, you have a secure job—especially if it’s an important piece of the system. But that job security is a chain that binds. In addition to indicating distrust of your team or management, it also means when a different, better, internal opportunity comes along, you won’t be able to take it. Since no one else knows how to do your job, you’re stuck.
Not exactly good for your personal growth, eh? And that is the best-case scenario. It assumes that your team won’t work around you and devalue the code that you’re “protecting.”
Well-written developer documentation scales your knowledge across your team, organization, or the world.
Sincerely,
Dan
Always be journaling
Brooke Kuhlmann has been developing software for ~20 years with an emphasis in the Ruby and Elm languages. He runs Alchemists, a collective devoted to the craft, quality, ethics, and security of software engineering.
Dear new 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 every day might 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 them to present situations will help you make more informed decisions.
Additionally, journaling serves another purpose; 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. 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, for example:
Format: <year>/<month>/<day>/<hour>/<minute>/<second>
Example: 2018/12/01/10/10/10
Work—Lessons learned from paid work. In addition to the benefits of helping you stay organized and not letting 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, and so on that might be worth sharing in a public forum at some point but currently are raw material.
Personal—For private thoughts and ideas of use only to you. This might include your health, mood, personal reflections, or relationships.
For tags, you might want to use a single tag or multiple tags in order to 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.” Using multiple tags helps connect related journal entries across categories which is another nice way to group information.
Bear—Supports macOS, iOS, and 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—Supports 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 getting started with 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 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 enough, try scheduling an end-of-day reminder to reflect on the day’s experiences.
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.
Fantastical—If task managers are not for you, consider investing in good calendar software and set up recurring events/reminders that way.
Reminders—Doesn’t have a lot of bells and whistles but will help get you started until you outgrow it. Free for macOS and iOS.
Reviews
In order to learn from past mistakes and experiences and build upon earlier lessons, it is important to review and reflect 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 or course correct.
Personal results
A stronger writer—As mentioned earlier, since I’ve been journaling, I’ve found I’ve become much stronger when writing git commits, responding to group chat responses, creating pull requests, replying to emails, and so on. 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 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
You should blog
Dear new developer,
A blog is free, forces you to think, provides an example of your ability to explain concepts, and helps others.
What’s not to like?
The hardest part about blogging is doing it. Now, I am no Fred Wilson,3 who blogged every day for 15+ years, but I have blogged since 2003. I’ve written at least once every month of those years, except one—I must have been super busy in November 2011.
From personal experience, I can tell you that blogging probably won’t get you a job, but it can lead to contracts. It won’t make you a superstar but will provide credibility. It won’t make you an excellent writer, but it will improve your ability to convey your thoughts.
What should you write about?
This is one of the questions I am asked whenever I suggest starting a blog. There are many possible answers: the latest problem you faced at work, the technology that interests you, or simply excerpt and comment on an interesting story.
Blogging reflects an ongoing curiosity about software development or whatever topic you choose. When you commit to writing one, you're not searching for a broad audience. But a regular blog will attract those with like-minded interests.
It doesn’t really matter what the topic is as long as you are interested in writing about it. Technology changes fast enough and is broad enough that you’ll always have something to write about. For example, if you are passionate about JavaScript, possible topics include how you set up your JavaScript coding environment, a new keyword you learned, the difference between === and ==, or the way you debugged a troublesome issue. You are writing to learn, for the clarity prose brings, and to share your knowledge with the world.
Don’t reveal any trade secrets of your employer, however. If you have any inkling that what you are writing about might be sensitive, run your desire to blog by your manager.
One more thing: You must commit. Six months is a good minimum.
The commitment matters. The benefits of blogging don’t accrue on the first or second post, but on the twenty-first or twenty-second. Search engines start to notice your blog after a couple of months. You can review your posts and see patterns. Someone who you don’t even know will read a post and find it useful—it is inspiring when a stranger emails you out of the blue and thanks you for what you’ve written.
So, how do you start?
I was at a conference once. During a question and answer session, I was asked about how to start blogging. I started to spout off about using WordPress, and the questioner clarified: “What about Medium?”
I stopped short. The correct answer was actually “whatever is easiest.” The technology is immaterial, especially when you are starting. Here are some tips on what actually matters.
Realize that almost no one will read your blog, especially in the beginning. Now, why would you write if no one will read it? To clarify your thoughts, to provide yourself a written record, and because, if you keep at it, Google and other search engines will find it.
Search engines are great at exposing the long tail of the Internet. If you write interesting posts, eventually Google will find it, and real live people will follow.
First six months of visitors and posts for the Letters to a New Developer blog
Month | Posts | Visitors |
|---|---|---|
September 2018 | 8 | 5 |
October 2018 | 11 | 20 |
November 2018 | 6 | 15 |
December 2018 | 9 | 219 |
January 2019 | 8 | 221 |
February 2019 | 9 | 223 |
For the first month, I wrote more posts than I had visitors! For the first three months, I wrote 25 posts and had 40 visitors. If you aren’t ready and willing to commit for six months, your blog will be one of those slightly sad blogs with three interesting posts, then one post six months later with the title “I haven’t posted in a while…” and then silence.
Now, if occasional posting is what you desire, that’s fine—there are many different reasons to blog. But if you are looking to be read by others, an abandoned blog won’t help.
I wrote out 10–20 exciting blog post titles. If I couldn’t come up with that many ideas, I was not passionate enough about the topic. That’s okay. Better to find out before investing the effort of writing one or two of them.
I emailed myself whenever I had a blog post idea. This let me search my email when I had time to write but no ideas. You can capture ideas with a spreadsheet, doc, Trello board, or to-do list. Just make sure you capture the inspiration when it strikes.
I made occasional posts easier by excerpting interesting articles or writing a response to ideas presented in other blogs or articles.
I wrote blog posts ahead of time and scheduled them to post weekly. When the muse is present, it feels easy to write a few posts. When the muse is absent, prescheduling let me take a break while still displaying consistency.
I realized and accepted that some of my posts were average or even mediocre. It is embarrassing to put out crappy content. Don’t do that. But some posts are better than others. Volume is key, and the longer you blog, the better your typical post will get.
As far as blogging software, the topic of that question asked at the conference I mentioned above? Use whatever is comfortable and easy. That may be WordPress.com, Medium, or Hugo/Middleman/Jekyll/the latest shiny static site generation framework.
Whatever you choose, don’t let the technology impede the writing. As a developer, it can be more fun to be in the weeds tweaking your blog deployment pipeline or page compilation than it is to write a post. At least it has been that way for me. But focusing on the tooling will distract you from your goal, which is to write.
My final tip is to share your posts in online communities. This creates links and traffic. It will also put your content in front of knowledgeable people who will poke holes in your logic and challenge your ideas. This process hurts sometimes, but feedback will make your writing better.
Which community should you share your posts with? Find where your people are. There are many online communities, whether tech specific like Hacker News, general purpose like Twitter, or focused and private like a DevOps Slack. Sharing is how I was able to increase the number of visitors to my blog in December 2018.
It doesn’t matter which community you choose, as long as you are an active member and sharing an on-topic post. However, don’t share only your own work; that’s self-promotion, not community participation. Find other interesting links, add comments, or answer questions. I find community members are skeptical of newcomers who join, drop their own links, and leave. I have received scoldings when I posted links that I thought were interesting but were not in line with the community’s values or tastes. It stung, but I accepted the judgment, acknowledged my mistake, and did better afterward.
Blogging requires a plan. It’s a great way to amplify your voice, display your expertise, and share your knowledge. Commit to it and set yourself up for success.
Sincerely,
Dan
Motivation
Dear new developer,
Writing crystallizes my thoughts—Writing, especially a deep technical piece, clarifies my understanding of the problem. If it is public, it is like writing an email to the world. Sometimes my writing process turns up issues or concepts not previously considered or other questions to research. It’s easy to hold a fuzzy concept in my mind, but when written down, the holes in my ideas are evident.
Writing builds my credibility—I have made money because people found my blog. I’ve had people interview me for positions and mention it. It’s easy to say “I know technology ABC” in an interview or consulting discussion, but it is more powerful to say “Ah yes, I’ve seen technology ABC before. I wrote a post about it, let me send that to you.”
Writing helps others—Friends looking for help with a technology or tool sometimes mention they found my blog while searching. Given the size of the Internet, this warms my heart. I’ve searched myself and stumbled onto a post of mine. The post solved my problem, so I was appreciative of my past self for taking the time to write it. I have been helped tremendously by others’ docs, so I consider writing “paying it forward.”
I write in public far more often than I write in private. But writing I share with no one has helped me think about problems I had or issues I faced as well. I don’t often review what I wrote, but the act of writing forced me to confront my thoughts.
Writing in public for years, on the other hand, has helped shape my career. It’s a historical record both prospective employers and I can review. It illustrates my ability to convey technical information and context.
Once an interviewer confessed to reviewing my blog. We had a discussion around the technical details of one of my posts. I got that contract.
Sincerely,
Dan
In conclusion
For software engineers, writing understandable prose is invaluable. The systems we build can be immensely complex, long-lived, and maintained by many people. This means that we must document them. Humans have found no better way than text to densely convey information over long timeframes.
But writing is also good for knowledge with a shorter life span. Whether that is a quick question on a chat system, a blog post, or a note to yourself, the act of writing forces clarity in a way that speech or thoughts do not.
As developers, we often focus on programming and technical skills. Writing well is often dismissed as a “soft skill.” But communicating ideas is something that both code and writing do, each in their own way. Practice your writing, focus your thoughts, and hone your ability to communicate.