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.
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)
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!
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.
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.
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.
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.
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.
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 😃
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.
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.
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.
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
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)
At work, we use excalidraw. So, I do the same. Not a fan but don't want to deviate from the rest.
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!
A good outline is a like a blueprint for your article. Thank you.
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.
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.
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.
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.
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.
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.
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.
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 😃
It is still a struggle for me. I gotta remind myself, stop being concise.
I am glad it resonated with you!
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.
Yea! Though, I feel, writing for newsletters is harder than writing at work :)
I don’t understand the last illustration. “Your potential is smaller than you think and can easily go downhills?” lol
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.
Thanks for explaining. That was definitely not obvious 😆
haha pictures are supposed to simplify, seems like it didn't work as well this time :)
Do you have any examples of great docs