How to Get Started with Technical Writing

Whether you’re doing dev rel as a full time job or just building your career, writing is going to come up a lot: CFPs for conferences, blog articles, even your bio. Some of these are technical, some of them are actually sales copy (CFPs are a form of marketing yourself 🤯). Heck, even tweets are a form of writing.

We’ll start with a great format to get you writing quickly, then we’ll talk about platforms for writing and paid writing programs. I'll leave you wtih some of my best writing tips and a bunch of resources to help going forward.

Let's dig in!

A Simple Format to Get You Out of Your Head and Writing 📝

There are many different formats for articles:

A resource round-up: “The Best Resources for Learning Go from Scratch”
A step-by-step tutorial: “How to Set Up Apollo Server”
An architecture overview: “How App X Implements the Mediator Pattern”
A deep dive into a technical concept: “What is Functional Programming?”

If you’re overwhelmed by where to start, let me give you a great format to help you get going. I call it the TIL (Today I Learned) format. Here’s how it goes: whenever you learn something small, just write down the problem that you’ve solved and the solution that you’ve found and publish it. Like this:

I. Intro: 2 or 3 sentences describing the problem you had.
II. Body: A few sentences describing the solution and how you got there.
III. Final solution: The finished code someone can copy and paste.
IV. Conclusion: 1 or 2 sentences re-capping the problem and solution with a link to your Twitter or a shout-out to your newsletter at the end.

This format does a few things for you. First, it solves a problem for other people. There’s a good chance that whatever problem you’ve had, someone else has to. Now you’ve just given them a resource to help. Second, it gives you a stubbed out article that you can always come back and add to to later. You might find that people are asking you to clarify something. Great! You can update the article and remember that for next time. Finally, it helps build the muscle of writing, editing, and publishing something. Don’t worry about the length, just get it out the door.

If you did this even once a week using something you’ve learned at work, you’d have 52 blog posts in a year. That’s a ton! But don’t think about that right now. Just think about one post at a time.

Platforms: Where to Write 💻

Okay, so we’ve talked about a format for getting started, but where should you actually write? Honestly, the short answer is that it doesn’t matter nearly as much as you think. Seriously, don’t overthink this! If you stick to a format like Markdown, you can always move things later. What’s important when you’re getting started is building the muscle of writing. As you build the habit, you’ll start to learn what’s important to you, like the formatting of the code snippets or the ability to create custom components.

Hosting Elsewhere 🌐

If you don’t want the hassle of maintaining a platform (which is a great decision in the beginning), here are a few good options:

Dev.to - Dev.to skyrocketed in popularity when Medium started introducing weird paywall features. It’s a great platform and a friendly community.
Hashnode - Hashnode’s blogging platform has really taken off lately. I like all of the ways they try to engage their community.
WordPress (.com) - This is the paid hosted version of WordPress.

Using one of these options will save you the time and headache of maintaining and deploying your own site and just focus on writing.

Pro tip: If you ever decide to move from one of these platforms to your own site and domain, you can always update the canonical URL to tell search engines that the version on your domain name is the source of truth.

Self Hosting 💪

If you'd rather host your own site, here are a handful of different platform options:

WordPress - For some reason developers love to dunk on WordPress, but there’s a reason it’s been around for over a decade. It’s a solid, robust platform with a huge ecosystem. You can’t go wrong with WordPress.
Ghost - Ghost is sort of the open source WordPress. It’s versatile, has great API support, and is continuously being worked on. I used Ghost for several years.
Gatsby - Gatsby is a React framework and static site generator. I have a hefty course on Gatsby to get you started.
Eleventy - Eleventy is a JavaScript alternative to Jekyll and a simple static site generator. It supports a lot of different template engines and languages.
Scully - Scully is a new static site generator for Angular. It’s got some very cool tooling and a plugin system to make it extensible.
Hugo - Hugo is a static site generator for Go and is very well loved by that community. I’m trying to think of a negative thing I’ve heard about it.
Jekyll - Jekyll is one of the oldest and most stable static site generators out there and runs on Ruby. It can be a little difficult to scale and plug in to CI/CD, but it’s super reliable and a proven platform.

By the way, pro tip: the Digital Ocean Marketplace has a bunch of 1-click deployments for a lot of these options.

Side Note on Content Management Systems (CMS) 📚

A really interesting development in the world of technical writing is the advent of some very nice headless Content Management Systems (CMS). This basically means you can host your actual articles on a different site that is optimized for managing a bunch of written pieces, but then pull that content into your blog. Most blogging platforms now support this, which makes it much easier to switch between platforms while keeping your content in one place. Here are a few I’ve heard good things about:

Sanity - Sanity comes with an open-source editing environment called Sanity Studio that you can customize with JavaScript and a real-time hosted data store. Sanity has generous included quotas so getting started is free.
Contentful - Contentful is a content management developer platform with an API at its core.
Strapi - Strapi is an open sourced Headless CMS. It’s more than a Node.js Framework and more than a Headless CMS, it saves API development time through a beautiful admin panel anyone can use.

Here’a a list of the top content management systems as well.

I haven’t used these much myself, so I’d love to hear if you have and what your experience has been.

Paid Writing Programs 💰

Once you get going with writing, you might be wondering: can I get paid for this? The answer is a resounding yes! Good writers that create quality content are hard to come by. Major blogs, especially for SaaS companies, are constantly looking for great content. You can often make several hundred dollars for an article and work with an editor to help improve your writing.

I would make a list of these programs for you, but my friend Daniel Madalitso Phiri has already done it! Here is Daniel’s repo of Paid Community Writing Programs.

It's also possible to do technical writing full time. My new coworker Joey deVilla wrote up an incredibly thorough article on his hiring process for the same job I used to have as a Content Engineer at Auth0.

My Best Writing Tips ✅

I love writing. I’ve been a writer for nearly my entire life. I was that dorky kid in elementary school entering short story contests and I was that dorky kid in high school entering poetry contests (no I will not be sharing my insufferable teenage poetry 😂).

You don't need to love writing like I do, though. You just need to be good enough at writing to drive traffic to your blog, get you selected to speak at a conference, or build an audience.

When I joined Auth0 in 2018, I was originally on the Content team (which manages the Auth0 blog). It was the first time I had ever written full time for a living and it was tough! Way harder than I thought it would be. Writing as a hobby gives you a lot of flexibility, but writing with deadlines, topics chosen for you, and peer reviews is a whole different animal. Luckily, that experience forced me to get more succinct in my writing and more efficient in my publication process.

Here are some of my best writing tips that I’ve picked up over the years:

Writing is a skill that takes practice. The more you write, the better you’ll get at it. This might sound kind of obvious at first, but I think developers often think they should be naturally good at writing words since they are good at writing code. Because of this, they get down on themselves if they don’t see immediate success when they start blogging and give up way too soon. Don’t do that! Build a system for yourself so that you write regularly and get feedback so you can improve.
One of the most helpful concepts I’ve come across is that of a blog as a digital garden. Let go of the idea that you have to ship a perfectly complete blog article. Publish something good enough, complete enough, and then come back later and improve or add to it.
Every time you muster up your courage to hit that publish button, you’ve started to run a test. The response or lack of response to something you’ve written is data that you can learn from. It might be telling you that you need to grow your audience, or that your distribution method needs work, or that your subject matter needs tweaking. Try as hard as you can to not let yourself get discouraged, but to take that data and learn from it.
When it comes to any sort of sales or marketing copy, whether CFPs, landing pages, or sales emails, remember to focus on the audience. Put yourselves in their shoes. What do they want? As you're writing, use phrases like “You’ll learn…” to convey that. Don’t drone on about yourself.
You don’t need to be an expert to write about something. In fact, learning in public is a great way to test out ideas and document your progress. Chances are you know more than you think and writing when you’ve just learned something is extremely valuable. As we develop more expertise in a subject, it starts to get harder and harder to remember what it’s like to be a beginner and what struggles beginners have. Use that to your advantage.

Writing Resources 📖

Some of my favorite books and resources for writing:

Bird by Bird by Anne Lamott - This is a book about the craft of writing and getting better at writing but it’s lighthearted and playful. It’s so hard to sum up what makes this book wonderful but it’s an indispensable part of my collection.
The War of Art by Steven Pressfield - You know that constant resistance you feel any time you create something? Steven Pressfield does, and he has some amazing advice for dealing with and moving past it.
750Words.com - Want to get better at writing? There’s an old adage that writing 3 pages per day (750 words) is the key to building a good writing habit. To that end, 750Words.com is a web app that is optimized for exactly that. It gives you a blank page, counts the words, and lets you know when you’re done. It’s perfect.
Ulysses - Ulysses is a Mac app that is optimized for long form writing. I wrote Getting Started in Developer Relations using Ulysses. I love that you can group articles and notes together. I don’t like it for blog articles because the Markdown is a little funky.
Khan Academy has a wonderful free course by Pixar on The Art of Storytelling.
My friend Justin Borge runs a site called Help with Your Hustle to help people build side businesses. He wrote an excellent article called The 7 Simple Rules Content Creators Live By (To Get Noticed) that covers a lot of excellent strategies for writing articles that will generate traffic to your site. I've used them myself and they are really helpful!
Is it even possible to talk about writing without mentioning Stephanie Morillo? Stephanie’s books The Developer’s Guide to Content Creation and The Developer’s Guide to Book Publishing are basically essential tools for the developer writer.

Let me know if you found all this useful!

This article began its life as an issue of the Developer Microskills Newsletter. Each week, I send out a practical, actionable way to improve as a developer and developer advocate. Sign up below!