Why and how to improve your writing skills as a software developer

This is a guest post from Allie Cooper. Enjoy.

It’s one thing to be able to write good code, but professional written communication is something else entirely. The ability to efficiently and authentically communicate using written language is an often ironically underrated skill in software development.

This is something that new developers need to get over very quickly. “Obsessions with patterns and algorithms don’t serve anyone’s mission by themselves,” explains engineer and career coach Minh Pham. “While coding might be your latest skill set, it is by no means an engineer’s only skillset. Remember that at the end of the day, it doesn’t matter if your code is ugly, fancy, verbose or concise – the value you create matters. Strive to be an excellent communicator, a quality teammate, and an outstanding human.” In today’s increasingly digitized workplace, achieving these qualities means honing your professional written communication skills.

Writing is Essential to Software Development

Any veteran developer can tell you that non coding-related writing is part and parcel of the daily grind, which includes writing tons of bug reports, notes for yourself, documentation for co-workers, and other technical discussions over chat or e-mail. You might also be tasked with explaining technicalities in ways that can be easily understood by clients. And as Inc points out, all of this generates a permanent record of any and all significant ideas, incidents, and other facts pertinent to how you’ve handled the job. In software development, the way you write and communicate over work platforms defines a great majority of your work history.

While writing code defines your raw ability as a software developer, your written professional correspondence tells the story of your ability to work with others in an inherently collaborative and complex field. Today, the sudden digital migration brought on by the global health crisis has only made professional writing a more integral skill for thriving in the new and increasingly web-based workplace. This is as true for experienced developers as it is for those who are looking to pick up the skills necessary for the job, which brings us to our next point.

The Future of Coding Education is Written and Online

From basic coding courses to advanced degree programs, more and more future developers are learning essential skills through online means. And the pandemic has only increased their numbers. For instance, Code Platoon Coding Bootcamp online basic coding courses have allowed the U.S. Department of Veteran Affairs to continue offering software development skills training for veterans as well as their spouses. And for safety reasons, all classes have been moved online.

Meanwhile top universities have also made this switch to training software specialists online. Maryville University’s online masters in software development is an advanced degree program that’s 100% web-based as well, with the perspective of producing future software consultants, UX designers, web developers, and DevOps engineers. And while these programs do include video conferencing classes, the majority of the work is through written communication. As natives to online work, the developers trained in these online programs are already developing the writing skills necessary to thriving amid the current digital migration.

In short, the field of software development is only getting more competitive and web-based. And while there’s no shortage of genius code writers for companies to cherry-pick from online universities and coding courses, the combination of a great coder and a great online communicator remains rare.

Practice Makes Perfect

Whether you’re already coding for a living or still learning the skill, you already have plenty of opportunities to hone your professional writing skills. Strive to be succinct and straightforward with every chat message or e-mail before hitting send. Put yourself in other people’s shoes – think about how the message you wrote will affect you if you were the one to receive it. Remember that every unnecessary word only muddles already complex conversations about technical specifications. Grammar is important, but so is writing with the perspective of being as empathic and as concise as possible – which can also allow you to develop a writing style that won’t require grammatical gymnastics. Never play to your emotions and always write with a collaborative mindset. The better you can communicate with the written word, the more value you can bring to any software development effort.

Allie Cooper is a freelance tech writer who specializes in I.T. and software development. Her mission is to help software developers further their careers. In her free time she plays online chess and sails.

Learn in public

This is a guest post from Shawn Wang aka swyx. Enjoy.

Dear new developer,

If there’s a golden rule to learning, it’s this one.

You already know that you will never be done learning. But most people “learn in private”, and lurk. They consume content without creating any themselves. Again, that’s fine, but we’re here to talk about being in the top quintile. What you do here is to have a habit of creating learning exhaust. Write blogs and tutorials and cheatsheets. Speak at meetups and conferences. Ask and answer things on Stackoverflow or Reddit. (Avoid the walled gardens like Slack and Discourse, they’re not public.) Make Youtube videos or Twitch streams. Start a newsletter. Draw cartoons (people loooove cartoons!). Whatever your thing is, make the thing you wish you had found when you were learning. Don’t judge your results by “claps” or retweets or stars or upvotes – just talk to yourself from 3 months ago. I keep an almost-daily dev blog written for no one else but me.

Guess what? It’s not about reaching as many people as possible with your content. If you can do that, great, remember me when you’re famous. But chances are that by far the biggest beneficiary of you trying to help past you is future you. If others benefit, that’s icing.

Oh you think you’re done? Don’t stop there. Enjoyed a coding video? Reach out to the speaker/instructor and thank them, and ask questions. Make PR’s to libraries you use. Make your own libraries no one will ever use. Clone stuff you like. Teach workshops. Go to conferences and summarize what you learned. Heck, go back to your own bootcamp to tell alumni what’s worked for you. There’s always one level deeper. But at every step of the way: Document what you did and the problems you solved.

The subheading under this rule would be: Try your best to be right, but don’t worry when you’re wrong. Repeatedly. If you feel uncomfortable, or like an impostor, good. You’re pushing yourself. Don’t assume you know everything, but try your best anyway, and let the internet correct you when you are inevitably wrong. Wear your noobyness on your sleeve.

People think you suck? Good. You agree. Ask them to explain, in detail, why you suck. You want to just feel good or you want to be good? No objections, no hurt feelings. Then go away and prove them wrong. Of course, if they get abusive block them.

Did I mention that teaching is the best way to learn? Talk while you code. It can be stressful and I haven’t done it all that much but my best technical interviews have been where I ended up talking like I teach instead of desperately trying to prove myself. We’re animals, we’re attracted to confidence and can smell desperation.

At some point you’ll get some support behind you. People notice genuine learners. They’ll want to help you. Don’t tell them, but they just became your mentors. This is very important: Pick up what they put down. Think of them as offering up quests for you to complete. When they say “Anyone willing to help with ______ ______?” you’re that kid in the first row with your hand already raised. These are senior engineers, some of the most in-demand people in tech. They’ll spend time with you, 1 on 1, if you help them out (p.s. and there’s always something they want help on). You can’t pay for this stuff. They’ll teach you for free. Most people don’t see what’s right in front of them. But not you.

“With so many junior devs out there, why will they help me?”, you ask.

Because you learn in public. By teaching you they teach many. You amplify them. You have one thing they don’t: a beginner’s mind. You see how this works?

At some point people will start asking you for help because of all the stuff you put out. 80% of developers are “dark”, they don’t write or speak or participate in public tech discourse. But you do. You must be an expert, right? Don’t tell them you aren’t. Answer best as you can, and when you’re stuck or wrong pass it up to your mentors.

Eventually you run out of mentors, and just solve things on your own. You’re still putting out content though. You see how this works?

Learn in public.

— swyx

p.s. Eventually, they’ll want to pay you for your help too. A lot more than you think.

This post was originally published here.

swyx is a Senior Developer Advocate at AWS and author of The Coding Career Handbook.

How to say I don’t know

Dear new developer,

The honest truth is that you won’t know everything. No one does. The CEO, CTO, the team lead, that really smart senior developer on your team, none of them know everything. In fact, I bet if you asked any one of them if they’d been stymied in the past week, they’d reveal that yes, they ran into something they didn’t know how to do or how to approach.

Encyclopedic knowledge isn’t a good goal. You need to know how to figure things out. But when someone asks you “can you do X?”, you need to be prepared with the right answer, even if you don’t know how to do X. For example, I was tasked with setting up a static IP for a heroku application. I didn’t know how to do this. Rather than say “I don’t know how to do that”, I said “let me do some research and get back to you.” I also asked about deadlines and how high a priority this was.

I did some research, read some docs and came up with a proposed solution. I discussed it at standup with my team, including my boss, and we came up with a path toward implementation.

When you don’t know something, and someone asks you about it, there are a few things you must do.

First, you should tell them you don’t know. They might have some clues for you, or pointers to documentation. These can all accelerate your ability to do what is asked of you.

Depending on the situation, they may assume you know, based on their experience. For example, I work in the authentication space right now, with standards like OAuth and OIDC. When I first started, I had to ask what every piece of jargon meant, but after a few months I got up to speed. Now when I talk to other audiences, I need to be careful not to use too much jargon or assume what others know. One favorite technique I use is repeating back what someone said: “Can I repeat back to you what said to make sure I understand it? What I heard is that the OAuth code grant redirects to the client application after the user authenticates. Is that right?”

When you say “I don’t know” don’t stop there. Say “I don’t know, but I’ll find out.” Again, they may point you in a direction, but by adding that second clause, you indicate that you’ll solve this problem. You should also ask about timeline and priority if that hasn’t been communicated (by story points, a task tracker or in some other fashion).

Finally, do what you say you’re going to do. Find out what you didn’t know. Don’t be afraid to ask questions of your team members, spend time on the internet searching, set up your dev environment and tweak settings, brainstorm, get frustrated, and write down hypotheses that you can test out. All of these are techniques I’ve used in trying to figure things out.

Saying I don’t know, honestly, with a plan to remedy your ignorance, is a key part of being a software developer.

Sincerely,

Dan

You’re gonna be OK

This is a guest post from Jerome Hardaway. Enjoy.

Dear new developer,

So, you’re in the office, learning a million things a minute that you were never exposed to. Everyone around you seems super competent and you don’t want to take time away from them, but you have no idea what you’re doing. You feel like you should probably be a janitor instead of working on a million dollar web app. I’m here to tell you, you’re wrong.

Every person who seems competent has felt like you or still feels like you do, they are just better at hiding it. I know people who have been doing this work for years and feel silly at least once a week. Hitting your head against the tech wall is a rite of passage here and normal and whether they tell you or not, we have all been there. We have all either accidentally taken down prod, nuked the repo, felt lost, accidentally ran up the AWS bill, and just straight up sucked at this job. So long as you focus on having more good days than bad, you will be fine. More than that, you’ll do great, so relax cause we are all rooting for you.

— Jerome

Jerome Hardaway is a Developer Advocate at Quicken Loans and Executive Director at Vets Who Code, Where they help veterans get jobs in software by teaching them how to program for free.

You’re probably going to want to quit

This is a guest post from Mia de Búrca. Enjoy.

Dear new developer,

You’re probably going to want to quit.

The very qualities that make writing software appealing can also make it frustrating beyond belief. You’re headed down this path because you like to be challenged, to learn and grow. However, facing new harder problems day in, day out can take its toll on your morale. And keeping up to date, familiarising yourself with the breadth and depth of topics in this domain – it can be overwhelming. But if you’re reading this it’s likely you’ve already felt the deep satisfaction of writing code to be proud of, so I hope that by sharing my experiences, from early in my career and from a few weeks ago, you will be motivated to push through and keep enjoying the journey.

The Import

One of the first times I nearly quit was a few weeks into my first role as a dev. I was fortunate enough to land a great job at a small startup, and I was pretty awe struck by the talented and motivated people on my team. So after a while of pairing, I picked up a piece of work to try on my own. After doing some copy-pasta from other files and then tweaking I was chuffed and attempted to view the web page that would now be perfect, right?

Much to my dismay I was met with a blank page and an obscure error message. Baffled, bit by bit I undid all my changes, at each step feeling less worthy of the job, until nothing was left except one measly import statement. I could feel myself go red in the face as I still couldn’t understand what was going on. I should be able to do this, but I’m not good enough. Eventually, I turned to my mentor to admit defeat, and my panic dissolved when he said “oh yeah, this one is definitely confusing” then casually pointed out a simple syntax error. I realised that unlike him, I was not yet equipped with the necessary debugging skills, I was not yet familiar enough with the language I was working in to decode the error message. It takes time.

The Library

It has been four years since the import statement that stumped me, but just a few weeks ago, when I volunteered to update a library which was many versions behind, this seemingly trivial task wound up with me ready to quit yet again. Between a broken development environment, failing tests (was it the tests… or the code?), and still this library integration that refused to obey, I was at a loss. I should be able to do this, I should be good enough by now surely? These thoughts drove me to stubbornly dig my heels in and devote hours to diving into the library source code, reading in circles, dipping in and out of StackOverflow, getting more and more frustrated. Much time wasted I was no better off, so I went and made myself a cup of tea and called up a colleague and good friend to lament my problem. Typically, within seconds of this accidental rubber ducking session the solution to my worries became apparent.

The Lessons

And I could probably list countless other occasions. There may be many different things that leave you feeling like quitting, for me it often boils down to not feeling good enough to tackle a problem. But when you come up against a roadblock, you shouldn’t see it as a reflection on your own ability. If like me you find yourself paralysed by feelings of inadequacy, recognise that the foundation of all programming is problem solving – if there were no annoying problems, you wouldn’t have a job – and as you progress through your career you will gain more tools to solve them. Step back and remember, when it comes to tech, there is a reason to be found – sometimes it takes time, distance, or some help to see it.

These are lessons you should try to internalise, or like me you’ll relearn them throughout your career. You can’t change the fact that deeply frustrating problems are coming your way. You can only change your perspective. Put your energy into solving the problem and don’t assume that you’re not good enough. “Good enough” is an arbitrary concept, an ever moving goalpost. Give up on the notion of “good enough” and instead give yourself some time.

Sincerely,

Mia

Mia de Búrca is a Senior Software Engineer working full stack at 99designs, a company connecting creatives around the world. Originally from Ireland, Mia started out as a translator and computational linguist before landing in Melbourne, Australia and setting her eyes on a career in web development. Mia enjoys solving problems with a focus on bringing real value to users and seeks opportunities to create a supportive and empowering workplace. When not hiding from apocalyptic pandemics, Mia is also a circus performer and teacher.

What’s your best advice for a new developer?

Dear new developer,

Dev.to is a relatively new community of developers. A few years ago, someone on that community asked for advice for junior developers, and I found the answers fascinating. Here are a few of my favorites.

People should respect you. It’s your right to push back against disrespectful interactions. If it’s waved away with “oh, [person] is just like that,” know that a) that is bullshit and b) both the person being disrespectful AND the one dismissing it are wrong. – Sarah Mei

Respectful communication and interaction is the foundation of trust, which is the foundation of team building, which is the foundation of software delivery.

Not getting your pull request through code review first time is okay. Everybody has their own approaches to problems, and a comment on your code review saying “X could be improved by Y because Z” doesn’t necessarily mean you’re not a good enough developer for only thinking of X, rather than Y. It’s usually more a case of your haven’t encountered a scenario that leads you to see the reasoning Z that causes you to use Y over X yet. – Aidan Walters-Williams

We all have something to learn. And our code is not ourselves, so when someone tries to improve our code, they aren’t attacking us.

Reporting a problem you’ve discovered is good, thorough analyses are better, proposing a solution is best. It doesn’t have to be right, it just has to start the discussion. – Dian Fey

It’s always good to go a step beyond reporting a problem because a) additional investigation may reveal it isn’t actually a problem and b) if it is a problem, the more you provide up front, the easier it will be for anyone trying to solve the problem (including future you) to replicate the context and hence investigate the problem with less effort.

There are a lot of great gems in the post.

Sincerely,

Dan

You’re going to put some plates in toasters

Dear new developer,

I saw this insightful tweet:

The whole thread is worth reading, but you get the basic idea. Sometimes you don’t know what you don’t know.

When I think back over the years, I am amazed at how many things I can do without thinking now that would have been baffling to me at the beginning of my career, including technical and non technical knowledge). This list includes:

  • navigate files and directories work
  • examine an HTTP call
  • determine the performance characteristics of an application
  • refactor an application
  • architect a large application
  • run a meeting
  • plan a project
  • exit vi

The road is long. And I still put plates in toasters periodically.

Recently at work, I energetically revised a planning document, adding what I thought was a ton of insight and value. Later I found out that the value I added was actually negative and that I’d done more harm than good to the organization’s goals when adding my thoughts. Man, was that a humbling and learning experience. Actually, that was more like putting a fork in a electrical socket than putting a plate in a toaster.

Much of what I know is at a high level with the idea that I can dive in (using resources like Google or Stackoverflow or a mentor) if I determine a need. Just knowing that something exists means that I can leverage all the great learning resources available if I see a place where it might appy. I also do a lot of pattern matching, where I compare how one system or process worked and see if and how that knowledge applies to a new problem.

So when you find yourself floundering, take a deep breath, forgive yourself, and dig in to learn. Foundational competence is something that you will acquire with time and study. But until you do, you’ll be putting plates in toasters.

Sincerely,

Dan

Learn an IDE

Dear new developer,

Just like you should learn a text editor, you should learn an integrated development environment (aka IDE). This is typically a standalone program focused on one or more programming languages. They range from free to a couple of hundred bucks in pricing.

Using an IDE will give you the following benefits:

  • It will be easier to navigate a project. Typically IDEs have a tree view of the entire project. Especially if you are not familiar with the command line, having this may make it easier for you to see how pieces of the project fit together. If the language supports it, an IDE can provide powerful searching capabilities, allowing you to see where a function, method or class is used.
  • Often these have refactoring support. Refactoring allows you to easily rename variables, functions/methods and files. If the language or IDE support it, references to the renamed entity can be updated as well. This will help make the code more fluid.
  • Debugging and code inspecting capabilities can be very useful. You can walk through code that is running locally and see the state of variables and make function calls. This is especially helpful if you have a test that can drive the code and replicate a bug. You can also, if the language supports it, connect to remote servers. (Many languages have command line debuggers as well, but it’s usually easier for a new developer to use an IDE.)
  • The IDE can provide text manipulation functionality. For instance, if you want to add documentation comments to every method, or an easy way to generate boilerplate methods, IDEs can provide this. It’s often easy to customize to your needs as well.
  • Easier learning the language or framework. If you are not sure of the exact name or syntax of a library call, an IDE can suggest it (often based on you typing a few letters). The documentation is often integrated as well, so you can, for example, see the javadoc by mousing over a method call (in a Java friendly IDE).

Obviously, as you see above, an IDE is very powerful. It’s also very tied to a language and the language’s features. If you are using a dynamic language (PHP, ruby) your IDE will have different capabilities than if you are using a statically typed language (C#, Java). But in either case, mastering your IDE will make it easier to write and debug code on your development computer.

Sincerely,

Dan

“It never gets easier, you just go faster.”

Dear New Developer,

Congratulations! Let’s take a moment to celebrate the decision you’ve made to launch or redirect your career. What lies ahead is a lot of hard work, satisfaction, the occasional desire to throw your laptop out a window, and a ton of learning. That’s true of most professions, so you’re also in good company.

As a developer, you will solve a thousand puzzles, and then a thousand more. Your brain will stretch and grow. You will dream about databases or pixels or curly braces. I once had a dream where I was walking down a hallway, but the hallway was my code. It was a good dream. I found a bug.

Greg LeMond, a pro cyclist and three-time Tour de France winner, once said something about cycling that I want to share with you: lemond

“It never gets easier, you just go faster.”

In so many ways, that describes a career in software. The puzzles you struggle with today will be easy in a month or a year. You’ll learn new patterns and best practices. Then you’ll take on new, harder challenges. You’ll struggle with those and learn and grow. Then you’ll start the cycle (pun intended) all over again.

Something I’ll add, though, is that you’ll be able to approach later challenges with more experience and confidence. What we bring to our jobs is an accumulation of skills and experience. This isn’t linear. It sometimes goes smoothly, sometimes it’s faster than we imagine possible. Then there are stretches where it feels like we’re clambering around in the dark.

For instance, I was once asked to write a WAP application (think super early mobile apps before smart phones existed). I had absolutely no idea what I was doing and I was mostly left alone on the project. I started by drawing some screens, took a deep breath, and started building. It was really tough going, but so many lessons have stuck with me from that experience. My skills at breaking down challenges and approaching them bit by bit really improved. I became comfortable throwing away code because the first code I wrote was atrocious. Plus, the project was eventually canceled, which was entirely the right business decision. Through that, I learned about evaluating tradeoffs in terms of business value—my time was better spent on higher priority projects.

In my current adventure, nearly 20 years later, I’m once again writing a mobile app and applying all of those lessons. Picking up languages and frameworks that I haven’t used before is far less daunting. Ensuring that I’m working on the most important thing is a constant recalibration, but one that is comfortable now. Working through stumbling blocks one at a time and having patterns for getting through them is second nature.

Just like learning isn’t linear, neither are careers. Your path will be your own. What you are doing today may or may not be what you’re doing in ten years. You might go into any number of other areas in software, or stay the course as a developer. It’s your life and all those choices are equally valid. One of my former colleagues quit to make hand-built microphones; another makes goat cheese in the Catalan Pyrenees. My personal philosophy is that at each opportunity to make a career decision, you should pick the direction that interests you most. Just like you learn faster when you are interested in your subject, you will ship better software (or make better cheese) when you are interested in your job.

There’s much more I’d love to tell you, but this letter is growing long. I’ll add some concise tidbits before I end.

  • You belong here. Try not to doubt that.
  • Get really good at debugging. It’s a skill and you will need it.
  • If you don’t respect your boss, or if they don’t respect you back, go find a new one.
  • Learning is part of your job. Make time for it.
  • Don’t be afraid to put your code in production.
  • Be a good team member. You will accomplish more and learn faster.
  • Ask lots of questions. Someone else probably wants to hear the answer.
  • And finally, have fun! You’ve got this!

I wish you all the luck in the world!

Sincerely,
Rebecca Campbell

Rebecca Campbell said “hello, world” to software development more than 20 years ago. She started as a developer before moving into team management and then senior leadership, and is currently working on co-founding a startup. She blogs sporadically at nerdygirl.com.

You Should Play (A Lot) More

This is a guest blog post from Zach Turner. Enjoy.

Dear New Developer,

Don’t forget to play. I spent the year after undergraduate working and learning. My goal  was to find a job at a company and eventually I succeeded. However my passion dwindled because it was always put second to finding a salaried position. As a result, my desire to play with and learn about new technologies simply because they are interesting has dwindled and my enjoyment of my job has suffered.

Allow yourself to approach the world as a kid again. Buy an electronics kit and only do
the first example experiment. Learn Hello World in 30 different languages. Start a passion project without worrying about finishing it. If you do finish it, try rewriting it in a new language. Think about a tool (software) that you would like to use, no matter how small or silly, and make it. There is so much pressure to know the newest and most popular languages and frameworks, and have a clean GitHub repo full of complete, relevant, and useful projects. That is especially appealing if you’re looking for a job. Yes, you should have a couple projects that are showcase worthy and speak to your desire to competently code. You should also be able to speak to your desire to learn and solve problems.

At the end of the day code is just a tool. No one faults a carpenter for having multiple hammers. I mean have you ever seen the garage of carpenter or maker, they are usually a glorious mess of projects in various states. Play and don’t fear clutter. Clean as you go and organize if you must. I’d rather have the GitHub of Doc Brown over Patrick Bateman any day. You can be a competent, intelligent adult and still play. If you don’t want work to become a chore, you must play.

From,
Zach Turner

During the day Zach Turner is a software engineer at Culture Foundry, a full service digital agency. At night he is a maker of things useful, useless, and everywhere in between.