Writing has always been a topic that is near and dear to my heart. English was my favorite class when I was a student and when I headed off to college I had considered a degree in it (until I decided I didn't want to be a teacher). I loved writing short stories and even now I'll bang out an occassional poem when I'm in the mood. Although this passion is useful in my work to give me a good understanding of grammar and spelling, I never expected this love of the phonetic to translate into technical writing.
Technical writing is a very different beast from fiction, poetry, or journaling. The style often aligns more with an essay, but if you write in that format, it can quickly become far too dry for your audience. Putting in some wit to lighten it up always helps. But how much? Too much can make it come across as not serious enough.
At Codegarden 2024, I gave a workshop about technical writing and I re-imagined that talk into a "quick" bullet list for Adam and Rich's workshop on making an Umbraco Astro blog for Codegarden 2025. Now I want to share a bit of that wisdom with all of you! Whether or not you share my passion for writing, I have some quick tips that can help you give that unicorn sparkle when it comes to writing about tech.
Know What Makes Your Writing a Technical Article
At Skrift, we house a variety of different topics from slice of life discussions on remote work to deep dives into Azure deployments. One of these is a technical piece and the other is lifestyle. It's important to know that technical writing is a specific skill that is separate from generic blogging, one I would define as a set of technical instructions that contains a use case and is written with your own voice.
Now, this can sound a lot like documentation but it isn't. Documentation is a set of instructions, but it's dry and often voice-less (on purpose), and it usually doesn't contain a specific use case as to why you are doing something. In your technical articles, you should make sure to include your own voice and style as well as explain to readers why they should be using your technique as well as how to do it.
Define Your Audience Before You Begin
Knowing who you're writing for is just as important as knowing what you're writing about, otherwise you risk talking down to them because they're experienced or talking over them because they're a novice. If you're writing for multiple audiences, consider before you begin the best way to bridge the gap - perhaps including instructions such as "If you're already familiar with how to use Vite to build and compile your front-end assets, you may want to skip to the next section".
When I write, I almost always try to pick someone specific I'm writing to. Erica, my "Skriftie" colleague, often gets to be my "guinea pig" for instructions. This has multiple purposes! When you write, you can think about how you would explain to that specific person, and when you're done with the article you have the perfect person to review it and make sure they understood what you had to say and why. A persona can't target everyone, but if it's useful to one person, it will be useful to others!
Have a Distinct Voice
As much as instructions are important, to me this tip is the most valuable tip I can give you. While I don't think every article that's been assisted with ChatGPT is "AI Slop", the fact that the phrase even exists gives me pause and it should give you pause, too. Ultimately, people don't come to your blog to see what ChatGPT or other AI sources can tell them about a topic - they want to know what you have to say about it, and that is why your voice is so important.
In addition to that, storytelling around the technical is what keeps it interesting. Make sure you have an overarching narrative for your reader. A great way to do this is to start with a problem - hypothetical or specific - to explain why you are giving the tutorial, and then step through everything to solve it. This tells people why they want to take your advice, and gives them a potential use case of their own.
If you want ChatGPT's assistance for writing, I recommend using it instead as an audit tool to check your work against and give it a list of criteria that you should meet (always make sure you have an intro and conclusion!).
Don't Rely Too Much on AI/LLMs (for anything but auditing)
And that segues nicely into this point. I am personally in a rather neutral position about AI. I don't hate it, and I don't love it. I see where it's useful and I also see where it creates "slop". I find it very nice as a rubber duck for vibe coding/paired programming, but on the other hand also really "great" at wiping out everything that makes me "me" if I ask it to write a blog post.
You are the most important part of your writing, so keep that in mind whenever you think that AI could make your life easier and "just do it for you". What it can do for you is give you good feedback as a QA entity on what you've written. There is a great list on Notion of "prompts to fix slop", which might be a bit insulting if you wrote your post yourself, but using one of the templates and modifying it to evaluate what you've written is a great way to get some feedback without waiting for a co-worker or other editor to get back to you.
Consider the Length and Read Time
Developers are busy people, and while they may be passing time while on a train, the most likely scenario for reading your article is that they are trying to solve a problem. This means you need to balance that very important part about storytelling with getting to your point. Tell the story, but don't ramble - make sure people can find what they're looking for, which includes very clear links to external sources!
Write an Outline
I feel this step might seem a bit obvious, but in my strong opinion it's one we can't ignore. After we've completed a task - like cooking a recipe - it's important to remember how we did each step and in what order when we're giving the instructions to someone else. So, just jot it down quick-like then review it and consider if that actually makes sense. Easier to reorganize now than later!
Generally, if I'm writing about C# I start with the model (if there is one), and I think about the lowest level dependency and then move up from there.
For those of you who might be thinking that AI can do this for you, I'm going to already tell you I've had bad luck with it. The last time I gave it a bunch of snippets and asked it to organize it for me out of a gist, it outlined everything by file name - not great. I would do this step yourself!
Share Code Clearly
First off, I am going to say very clearly: don't screenshot your code. Copy-paste is one of the most useful tools we have access to and there is nothing more frustrating than seeing a screenshot of the snippet you need and having to manually re-type it. Yuck!
Your code doesn't have to be formatted all pretty in an article, it just needs to be readable. And if you really want to level it up, rather than telling people what to do around it in the article, add comments to it as well! That way not only do you explain the step, but if a reader copies and pastes it they understand exactly what they're doing in their own codebase. It's a win-win!
Handle Media Correctly
This particular section is not just about content entry but also about setup. A lot of people read articles on their phones, and a lot of the time we are posting screenshots from our desktop setups. With this in mind, I think it's good to ask yourself the following questions when you're working with media:
- Can the reader open an image larger and zoom in?
- Can they download the image later for reference? (some services turn this off)
- Do you have good alt text, and does it display as part of the caption? (see BlueSky's pop-ups on image click as an example)
Consider these any time you need to share media, and also remember that images can be really big and should be cropped well! Which also leads us into the next two points...
Don't be Afraid to Use Videos
Sometimes we write tutorials that require a solid chunk of setup for either the backoffice or third party tools. While you can use screenshots to show people what to do, I highly recommend considering if a video - or gif, but keep file size in mind - would be a better choice. My general rule is that if I need more than one screenshot to explain anything I'm doing in the backoffice, a short video that I can plop into my article is the right decision!
Understand when an Article isn't the Right Choice
Not everything makes a great technical article. Some tutorials make much better videos, presentations, or even demos. For me, a technical article is always a good choice when you want to share code because it's important to give your users the ability to copy-paste. They're also incredibly accessible as text is available to everyone.
But for those moments where you are explaining a lot in the backoffice or need a series of non-code screenshots, a tutorial video is better. A presentation or workshop (maybe at a meetup?) can be a great way to teach people how to use packages or interactive elements.
And, of course, mixed media is wonderful. Do a presentation? Write a complimenting technical article. Need to give instructions on the backoffice? Embed a video and then share the rest of your code.
TL;DR (Too Long; Didn't Read)?
That's okay, I'll sum it up for you. Remember that you're writing for other humans, so they want to hear from you - a human - and you want to make it as clear as possible for them to understand. That's the ultimate goal of a technical article.
Share your knowledge, share your voice, consider clarity and audience, and you'll be great. And if you're intimidated, don't be! Practice and trying is the only way we all get better at everything we do.
Happy writing!
