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:

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:

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:

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:

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.

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 Resources 📖

Some of my favorite books and resources for writing:

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!

Project list gathering dust? 👀

Drop me a line below so I can send you the Tiny Experiments framework and worksheet. You'll also join over 2100 other devs and dev advocates on the Developer Microskills newsletter.