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.
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:
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.
- The Why, What, and How of Internal Documentation
- Getting Started With an Incident Communications Plan
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.
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.
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.
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.
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.
I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!