This time last year, I placed a bet on the idea that software developers wanted to write more content and become better bloggers. This idea is not new, it's not novel: software developers have been blogging as long as blogging has been around and the field has benefitted from developers who have generously shared their knowledge in the form of articles and blog posts. In less than one year, over 1,200 developers have purchased my eBooks on content creation and have started their own blogs, newsletters, podcasts, and screencasts.
But while I've had the opportunity to see developers pour their writing capabilities into blogs (and there are plenty of good reasons to blog), the same level of enthusiasm isn't there for another form of writing that is just as impactful: business writing.
What is business writing and why is it important?
Business writing takes the form of emails, presentations, reports, and internal documentation, among other things. It includes everything from your team's quarterly OKR document to the technical spec you create for work items. This is the writing that keeps everyone in your workplace informed, trained, and it keeps things moving. Work gets done through business writing and business communications.
Written and spoken communication, we know, is a crucial skill to cultivate. It will affect everything from the amount of influence you have, to how colleagues work and interact with you, to how you move up in an organization. But few of us are taught how to create great Wikis, excellent presentation decks, or craft thoughtful emails. We learn these skills by trial and error, if at all. If we're lucky, we may work for an employer that offers training on managing meetings effectively, writing professional emails, or putting together a slide deck. But in the absence of formal training, we have to find other ways to pick up these skills.
With that in mind, here are five ways software developers can improve their writing beyond personal blogging as well as resources for each:
1. Contribute to your team's internal documentation
Internal documentation in all its forms — videos, process documentation, post-mortems, incident reports, etc. — is critical in engineering team operations. We create these assets for numerous reasons, including for tracking work, onboarding, and communicating process changes. Few people peruse internal docs for fun, but creating them and maintaining them increases knowledge transfer within teams (this is critical when hiring new employees or when people leave) and ensures consistency across teams. Docs are a scalable way of recording how, and why, your team does things and sharing that across an organization.
Bonus points: Make sure you socialize the existence of your docs to external and internal stakeholders. If someone has a commonly asked question that is answered in your docs, point them to the right document. Documentation is only useful if people know it exists and if they know what they can find there. Help people find the answer to their problems by pointing them in the right place.
Resources:
- The Why, What, and How of Internal Documentation
- Getting Started With an Incident Communications Plan
2. Get paid to write and work with an editor
Plenty of tech companies have paid writer programs, where they accept externally contributed guides and tutorials and compensate the author for their work. Companies will typically pair a writer with an internal editor who will review the writer's work, provide feedback, and edit for grammar, syntax, and other style issues. Working with an editor is one of the best ways to improve your writing because you are getting detailed feedback. They are showing you what needs to be improved, how to improve it, and why.
Resources:
3. Improve your code review process
Every team has its own norms and standards for how to conduct effective code reviews. But there are still ways to make your feedback clear, respectful, and easier to follow.
Resources:
4. Use templates for writing tech specs and reports
As is the case with code reviews, many teams have templates for their tech specs. But if yours doesn't, worry not — there are templates out there that can be tailored to your team's use case. Templates promote consistency (you're using the same format and including the same kinds of information and detail every time) while saving you time from recalling what to include. When I was in grad school, I had to write lots of reports. I looked for templates online for writing good usability reports and I found a template on Usability.gov that was so useful, I even adjusted it for reports I created at work. Today I have templates for everything from tech specs to how I format meeting notes to emails.
Resources:
5. Prioritize learning how to write better emails and chat messages
Many of us office workers went remote in 2020 due to COVID-19 and that meant more written messages. Email and chat are where a lot of interactions take place now and there are plenty of ways to get it wrong. In my 12-year career, I've never worked at a company that has given a "How to write good emails" class. I've learned it on my own. But if you want to be seen as effective at your job, reliable, trustworthy, and in general as a good colleague, make writing better emails a top priority moving forward. I recently released a 95-minute masterclass called "Writing Professional Emails" which shows you email features you must use, how to write emails in a variety of scenarios, and how to use email signatures, chat messages, and your work calendar to set boundaries. It's the email class you always wanted but haven't found – until now.
Resources:
In summary, personal blogging is one way software developers can extend their knowledge to others and improve their writing skills, but it's not the only way. Developers should also improve their business writing skills to help them establish a culture of knowledge sharing within their organizations.
This post originally appeared on my blog.
I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!
Top comments (10)
Great article, thanks!
I think that many people underestimate the importance of communication. Even the brightest or simplest idea will not be understood and appreciated if it is not explained properly.
One trick that I do to improve my writing at work (documentation pages, emails, etc) is to leave the text after I wrote it for 5-15 minutes, then come back to it and try read it from position of a target audience. If, for example, it is an internal documentation - I try to read from a position of a new hire who sees it for the first time and does not know all the concepts (then I try to explain or add links).
It makes it easy to identify pieces where my thoughts are not properly explained and understand if there are any gaps.
That's an excellent trick and one I practice myself. It's really helpful to step away to give ourselves time to remove ourselves from our initial responses (which may also be shaped by our emotional reactions). It's always, always helpful to ask ourselves questions from our target audience. In short, I agree with everything you've shared here. Thanks Igor! :)
Thank you. These are really cool tips, because I really have some difficulties with writing.
You're welcome, and thank you!
Very great article! This is what I was looking for. Thanks!
You're most welcome!
Thanks for great tips, Stephanie! :) Do you know any resources on how to write better articles or dev blogs? When is it a good time to start blogging on your own?
Hi Mateusz, I do, actually — my eBook The Developer's Guide to Content Creation. 😊 It contains eight chapters on everything from:
Over 1,200 developers have read it and I'm happy to share that most have started their blogs as a result of reading it.
There are also plenty of other articles and tips on my personal blog which you're welcome to read at any time. There are articles on things like technical writing there as well.
Best of luck!
Terrific article.
Gave me a very important topic about writing emails.
Is there any discounts for students from India for your course?
Thank you Gautham!