21 Comments
Feb 23Liked by Raviraj Achar

Thanks for this - very useful to see this written as a framework.

I'd also add - the document isn't the end of the process - share what you've written.

Too many good/great tech docs get added to internal doc stores and portals, and no one ever sees them. Talk with your team about what you've written, do a show and tell, put it in slack.

Expand full comment
author

Glad you found it useful.

Yea, sharing it important and I had shared good ways to do that https://newsletter.techleadmentor.com/i/141266993/dos

Expand full comment

Really great framework here. What do you usually use for visuals in your docs btw?

I usually use the in-built Google Docs drawing tool for design docs as they can be linked across docs (say, for a large undertaking that requires multiple docs but links to the same “context” image of the architecture)

Expand full comment
author

At work, we use excalidraw. So, I do the same. Not a fan but don't want to deviate from the rest.

Expand full comment

Great article.

I think one of the difficulties with technical writing can be one of the hardest things as a writer. An outline, even brief, I find makes a huge difference.

Will be keeping a note of this one as a framework!

Expand full comment
author

A good outline is a like a blueprint for your article. Thank you.

Expand full comment

Thanks for sharing. It's a big challenge for the developers, basically our brain struggles a lot to convert the thought process from machine language(code) to human language :).

Many developers feel the document should have been clearer and more concise when reading the others and struggles when they write it.

Expand full comment

Great article Raviraj!

For me "Create an outline." was an important one. I used to write as I found information, rather than giving structure.

Now I have my personal process with 2 docs. One is the "model" with the data, links, and stuff I find. The other is the "view" with the information neatly presented to reviewers.

Expand full comment
author

model & view - thats a nice way to present what is necessary to the readers. I do something similar with scratch pad and then the real doc to share the message.

Expand full comment

The background is my biggest challenge in writing, whether it’s technical docs or newsletter articles…

It’s so easy to fall into a long intro, that only you find interesting, and lose 90% of the readers.

Having an ideal reader, as you suggested, is very helpful.

Expand full comment
author

Yea, I still remember some docs where I went on and on with context. People don't always complain but I am certain they were bored.

Expand full comment

This bit really got me: “ I assumed my job was primarily to write code and that everything else was a distraction. I would scribble down a basic document and share it. Later, I would be annoyed when leadership had seemingly trivial questions. I even limited the time I spent on writing them. Thereby, I never invested in learning the skill.”

So much of our jobs as engineers is communication. Both written and verbal, and yet we often don’t practice it or work hard to improve it like we do with our coding skills.

Sometimes it just feels like a black box and a waste of time when we could be cranking out code or keeping our systems up and running.

Thought this was a great read with some practical steps I can use for writing better technical docs.

Expand full comment
author

Yea, that feeling is a lot more common. I saw it in many aspiring leaders. Though the best part was when they realized the importance of writing and that changed their point of view.

I am glad you found the steps valuable.

Expand full comment

Thanks for sharing your writing process in detail. I have gotten recently burnt because I tried to keep my document “concise” so totally relate to what you said here.

This write up helps. Especially you pointing out about treating the document writing as a chore 😃

Expand full comment
author

It is still a struggle for me. I gotta remind myself, stop being concise.

I am glad it resonated with you!

Expand full comment
Feb 22Liked by Raviraj Achar

This is a great framework to write by! Thanks for sharing it, Raviraj!

Just like in these newsletters, managing expectations for readers is super important. When you forget to set the tone in the first few paragraphs, you might lose them before they start reading.

If you don't deliver in the document's body, they might get confused and can't provide valuable feedback.

Expand full comment
author

Yea! Though, I feel, writing for newsletters is harder than writing at work :)

Expand full comment

I don’t understand the last illustration. “Your potential is smaller than you think and can easily go downhills?” lol

Expand full comment
author

I was going for a physics metaphor there. Any object that is at an altitude has high potential energy and as it rolls down the hill it gains momentum.

So the image on the left is saying you don't realize you are on the hill and have high potential "energy". But, in reality, your true potential is depicted on the right.

Expand full comment

Thanks for explaining. That was definitely not obvious 😆

Expand full comment
author

haha pictures are supposed to simplify, seems like it didn't work as well this time :)

Expand full comment