The Best Practices for Tech Writing

👊NOTE: Last week, Crystallize had a team gathering in Portugal, and I was tasked to talk with our devs about tech writing, docs, and blog. What you see here is the gist of that talk turned into a blog post.

Devs, why don’t you write more? What’s stopping you? Language? Topics? Lack of interest. Impostor syndrome? You don’t have it in you? I can go on...but... I hope it is a combination of you've never thought about writing before, and you just need a little more motivation.

Whatever the case may be, there are a couple of good reasons why you should start writing:

• Writing helps you grow as a person and developer. You see, by outlining your ideas on a topic of interest, you actually delve further into the issue at hand and have a greater understanding of what you learned, what you could have improved upon, or what needs to be changed right away.
• Writing helps you document your experience. Since brain memory implants are not yet the standard for humans, writing down your experiences will help you in the long run. For example, when you need to address a similar issue on a new project, it’s easier to have it written down already than trying to remember the solution. Or, if you write for the public, sharing your experience might help you get feedback from the audience and learn a thing or two.
• Writing is networking for introverts. I generalize here, but I’ve found most devs to be introverts (hell, even I am an introvert, but I fake the extrovert part of me). Seriously, by sharing your writing, you grow your network of internet friends across channels ie writing makes your networking that much easier.
• Recognition of your work and your expertise. I’ll talk about it a bit later.

You can write for yourself, which is fine, and you should do it, but I am not really interested in your diary (unless you have nice pics to share with it). Or you can write just like Franz Kafka did for the better part of his life. But waiting for someone else to release your writing after your death won’t help us as a company (unless royalties go to us). So, I’m not interested in that either.

However, I am interested in you writing docs and for our blog and in you covering dev topics for our growing dev audience.

That sounds great, but how do I start writing?

There are a couple of things you should be aware of right from the start. Don’t be put off by them. I promise you the rewards you get (besides a beer from me) are spectacular. So...

Finding the time

It takes a while to do proper research and write a post. It also takes knowing what you want to write about, your intended audience, and what problems you are solving for your audience with your writing.

Now, there are three types of posts you guys can be involved with in company and plenty more at free options like Dev.to, Hashnode, Medium, etc. But let’s stick to our company blog. I’m open to talking about others. You can DM me. So...our topics:

• Labor of love, i.e., topics you care about and you have an insight you’d like to share

• Topic/keyword posts, i.e., topics we as a company are interested in and would like to appear/rank for

• Case studies, i.e., posts/articles on things we do for our product and our clients
  Writing each one of these requires a bit of a different approach. But they also have a couple of common things you need to be aware of or tackle before starting writing.

Story and audience

Whatever you want to write about, you need a story as to why you are writing about it in the first place. What solution/value would be reading the post bring to your audience? What problems have you faced, and how did you overcome them? What did you learn?

I like to say that the best way to learn is from the experience of others and personal mistakes. That really seems to be the case when it comes to content and the internet, and the B2B approach. People read more and relate more to posts that are written from experience. That seems to be more and more true for Google results as well, being that it is getting better at understanding the intent behind the searched keyword.

So you’ll need to convey a story that would lure your audience and give them what they want, the way they want it.

We'd all be writers if there is a recipe for the above. There is none. But some tips can help you get better at writing. And that might help you nail the above.

Writing steps

1. Set goals. Know exactly how much time you have to finish writing.
2. Set a timer. i.e., I'll start now.
3. Find your external sources before you write. This is part of the research phase.
4. Create an outline. Structure before writing.
5. Force yourself to write straight through to the end. Don't self-edit as you go!
6. Write the body of the article and THEN write the intro.

Writing tips

Do proper research on the topic you are covering. Go beyond the first ten spots in Google search for a couple of keywords. Read a couple of those annoying Readers also enjoyed links. Reddit for answers. Follow the rabbit hole just as you would while watching YouTube or TikTok videos.

Make sure you are reading credible sources. Don’t look for sources that would only back up your claim. Look for sources that have merit to their word and would prove your claim is right. Or wrong.

Keep your content organized. That means you should have the beginning, the middle, and the end to your story. That also means you should organize your content by the HTML hierarchy. The elements are there for a reason, and the most obvious one is to keep your writing in an organized structure so the readers (and search engines), if they want, can skim the content.

For those interested in the black arts. Use the inverted pyramid style of content writing used by true journalists. The top of the inverted pyramid summarizes the most important elements of a story in order to draw the reader in and get their full attention. The parts that follow go into detail.

Make the TITLE and the first paragraph that stands out. You can write the best essay ever, but it would mean nothing if you fail to spark interest in your audience. In today’s world of TITLE skimming, having a catch TITLE and a first paragraph is all you have to spark an interest. The simple reason behind this, really. In today’s oversaturated digital world, the average human attention span is 8 seconds. Even goldfish (9 seconds) are better than humans.

Images and links draw attention. One way to tackle the attention problem is with images/videos. They re-spark attention. Walls of words are dull, however interesting a topic might be. Words and images are powerful when making a point or allowing a break for your audience (btw you don’t have to use gifs all the time). Links to resources that inspired you or helped you understand something or back up your claim proves you’ve done proper research.

Video content offers a more immediate experience with much more information served in a short time than a simple blog post. It triggers an emotional response much faster than simple blog posts, on which ENGAGEMENT can be, well, exploited. Engaged viewers are more likely to share the video with others. They spend more time on your website, thus allowing you to exploit them to gain exposure, increase your traffic, brand your product, or earn additional revenue with your video ads.

What about style/voice, grammar, and all that?

Well, no one can tell you how to write. Your voice/style develops and changes over time, just like you do. People don’t say practice makes perfect for nothing. I think your style is somewhere between the way you talk, dry tech documentation, the topic you are covering, and your target audience.

As far as grammar is concerned, even native English speakers get it wrong sometimes. The best we can do is play it by ear (like I do), use what you’ve learned so far (like I do), learn more by reading in English (like I do), and cheat with Grammarly or some other tool (like I do).

Why should you write?

You’ll make my job that much easier for one.

Word of mouth is the most successful way of promoting a brand or a product. Modern-day businesses have that option online, mostly thanks to social media. I’m not talking about shares, likes, reviews, and comments. I’m talking about the employer and employee branding.

Quickly, the overview of both.

What is employer branding?

Employer branding is a term associated with what a brand does to promote itself as a fantastic workplace. Today it is not nearly enough just to offer a good paycheck and the right conditions for a job opening. To get the best talent, companies need to stand out with their company culture and code of conduct that resonates with their candidates. And other perks (like annual retreats or beer money).

What is employee branding?

On the other hand, employee branding is usually associated with how to shape employees’ behavior so that they project the brand identity through their everyday work behavior. Employee branding is about getting your employees on board with who you are, what you do, and what you as a company stand for. Then, through social sharing and word of mouth, convey those brand messages in the best possible light.

Sounds fun, right?

For companies, there are huge benefits to practicing both of these. But here, I'd like to talk about employee branding from a different perspective, i.e., not what you can do for your brand but what your brand can do for you.

Benefits of employee branding

Promotion and building of your personal brand. The stronger the brand you work for is, the stronger your personal brand is. Think of it this way, when you see someone is working for Google, Facebook or Crystallize, you immediately assume he/she's got the knowledge. For startups, brand strength is built with product quality, marketing efforts, and employee branding (think Netlify, think their dev advocates, and how they, with their name, give strength to the company just as the company gives strength to their names.).

Credibility. By telling/sharing brand stories, you add credibility to the brand, the story itself, and your part in it. For example, Ahrefs CMO frequently shares its internal scheduling and hiring processes. By being transparent about what they do and how they do it, they influence how the community of their interest, SEOs, perceive them.

Authoritativeness. Being a part of an authoritative source/brand pours some of that authority on you as well (remember what I mentioned for people that work for Google, well...that’s it).

These three influence how people perceive you and your abilities. Are you someone that is in the know-how? Are you easy to work with? What are your main interests in a job? And by telling a story about your work, your company, and how you are telling it, you directly influence the brand you work for.

And YES, writing is one thing that works amazingly well for both us as a company and you as a PERSONAL BRAND.

Side note

Candidates who want to know more information about working for a certain company prefer talking to the employees of the company as opposed to talking to the employer. On the other side of the spectrum, HRs who want to know more about candidates prefer talking to previous employers.

Like it or not, we live in the age of social media, and to some extent, if it does not appear on soc. media it did not happen. I've learned it the hard way because I never actually wanted to participate in any kind of employee branding. TBH at one time, this diminished my prospects of finding new ventures because I did not have actual proof of work.

I opted out for a different approach i.e., provide value upfront when applying for work, which in my case worked, but I think it would have been so much easier for me if I had soc.media proof.

Then again, I would not become such a sweet talker :-)

To wrap things up...

Get active, get creative, and get going! Don’t be afraid of failure. You don’t think of it while coding, so why would you burden yourself with it when writing?