Being a Technical Writer in an engineering world can be tough. We work closely with engineers, but we're not engineers ourselves. Our job isn't to ...
For further actions, you may consider blocking this person and/or reporting abuse
lmao.
It's all fun and games until they actually remembers it. Had a friend like that XD
That counts as a superpower, I guess 😄
I'm the architect who writes the documentation that engineers don't realize they're following.
Why don't they realize? Do you mean you write architectural designs that engineers should follow for implementation? In this case, it's always good to have such docs as a reference and a checkpoint for what the team wants to achieve. Even if it's just an internal documentation, without it the goal would get blurry. Moreover, design docs can be later transformed into architecture docs for the project.
Keep doing your job 💪🏻
Engineers don’t realize it because the documentation I write isn’t a checklist of instructions—it’s the architectural substrate their decisions end up conforming to.
I design the conceptual boundaries, invariants, and failure‑mode constraints that shape the system. By the time engineers are implementing, those structures feel “obvious” or “natural,” so they don’t always see the architecture they’re implicitly following.
Good design docs absolutely matter—but the kind I write operate one layer deeper: they define the rules of the world the implementation lives in.
Glad to see that you realise the importance of the docs you write 🙂 It's actually a foundation for the implementation. I think this should be the starting point for every project and every big feature.
Type 6: Vibe Coder ✌
This is a case where the code works and you know its algorithms, but you don't know what's under the hood.
Good article!
So the mix of Jon Snow and Robot, I suppose? 😄
You have to experience this for yourself to understand. It will be something unique if you learn to use AI as an assistant, and not as a replacement.
That's what I'm discovering now and what I'm trying to introduce in my company. Unfortunately, I see a lot of people misuse AI, telling it to simply generate the docs for the feature and not even checking the output later. What I get is a load of text that is too heavy in implementation details, hard to understand, and definitely useless for the end user. As a Technical Writer, my job is to make it good, but it's much more difficult and time-consuming to extract useful content from this big pile than to go with the old style "messy short draft + dev interview".
I also believe that using AI as an assistant is the only correct way to use it; we are still on our way to learning how to do it right, though.
I used him as a teacher and learned a lot. If you're interested, click
One part of our heart is good and says to be nice and collaborative.
But on the other part, ego stares!
And when tired, we become robots.
And when mind is off, we become gpt lovers
So, all of em, based on place, time,team, situation and also season!
... and the intake of caffeine, as Julien mentioned above 😄☕️
honestly, the engineers who refuse doc questions usually have the most useful knowledge - they’re just protecting context that takes 10 minutes to explain but 10 days to rediscover
To the point! 💯 Hopefully, such engineers sooner or later realise that collaboration is a win-win both for tech writers and for devs, even if it takes away a bit of time one could devote to coding 😉
Worth adding: forcing the knowledge transfer often reveals the engineer didn’t fully have it themselves. Writing it down for a tech writer surfaces gaps in their own understanding. Half the friction isn’t protectiveness — it’s engineers running on pattern-matched intuition with no real spec behind it.
Also true! 💯 That's why following the docs-as-code approach helps to notice the gaps in understanding at an early stage and prevent mistakes in implementation. Docs could be a very useful resource; unfortunately, very often underestimated.
yeah the ‘has to compile’ constraint is what makes it work - you can’t be vague when something downstream depends on parsing it. breaks earlier than prod does.
DEV needs to add a laughing reaction haha
Agree 💯! There are plenty of humorous posts on dev.to, would come in handy 😄
Wao Great Article 😉😄
Thank you for your kind words, Harsh! 😊
Publishing a first article is definitely a big step out of the comfort zone!
Nice article! Technical writer sounds like a fascinating job.
I would say I can be a golden boy if I had my cup of coffee in the morning :)
Thank you, Julien! Obviously – no coffee no workee ☕️🙅🏻♀️ I suppose this works for many professions 😄
And yes, technical writing is very satisfying! Especially seeing the project getting properly documented over time and engineers getting better at documenting! 💛
Haha very true !
What is your definition of 'properly documented', ie. what makes good documentation according to your experience ?
Also what arguments do you give to engineers to convince them documentation is important ?
Glad that you asked! 💛 I'd say good documentation is about two things:
If the user cannot find the information they are looking for, they will quickly get discouraged. That's why easy navigation and a clear documentation structure are crucial, especially at the beginning when the user doesn't know the documentation portal. Also, you must know your target audience and adjust the language and the level of detail to their needs. Content that may be helpful for ops will not necessarily be understandable for an end-user.
Unfortunately, convincing some devs of the importance of docs can be a way through hell 😄 Some of them learn it the hard way – for example, when they find an answer for some production issue in the docs. Fortunately, most of the time, it's enough to talk and make the engineers aware of the end user's needs. In the end, we have a common goal – to deliver a usable product 🙂
Got it! Thanks for detailing this.
If you are looking for future post ideas, a deep dive into documentation best practices and sharing some of your key learnings would be super helpful, I would definitely read it :)
Thank you, this is very encouraging! 💛
I love a Golden Boy (or Golden Girl)! What's the most common archetype you encounter?
Fortunately, it's a golden one! 😄 There are many collaborators out there in the tech industry! It happens that engineers admit they don't know how to write good docs, but they are open to collaboration, and together we can create content that is clear and easy to follow.
A bit concerning is the recent trend of generating loads of docs using AI (see: Robot). It can do more harm than good, as extracting useful content from a generated mess is very often more time-consuming than writing a messy but concise draft that tech writers can later use as an input for the docs. This is actually a much bigger topic – maybe even worth a separate article 😄
It is definitely worth!
Thank you for your support @0xax ! 💛
I consider myself the first type, because I have all these characteristics! Houf houf houf 🐶😄
Good job, keep going like that! 💪🏻
BTW, I can see you are both a dev and a technical writer. How do you combine these two? What challenges do you face?
So, I always try to create something different. There is a lot of content on the internet, but in many cases it is superficial, and sometimes there is too much information in a single post, which is not ideal either. In my case, I always try to find a balance. I prefer to focus on a single topic per post and highlight the main points. Whenever possible, I also create visual flowcharts because they help readers understand and retain the content more easily.
Another important aspect is that the content should deliver what the title promises. Sometimes, I receive questions from readers. For example, in a post about Authorization Methods, one reader asked: “Why didn’t you mention the refresh token approach?” In these situations, I always try to respond politely and explain that the main goal of the post was to demonstrate how that specific authorization method works. However, I appreciate the suggestion, and I may cover refresh tokens in a future post. After all, if I tried to include every detail, the post would become too long and difficult to read.
Another point is that some topics are not ideal for tutorials, such as publishing an application to a cloud platform like Microsoft Azure, because these platforms constantly change their interfaces. As a result, tutorials can become outdated very quickly, which may confuse readers or lead them to make mistakes.
I also write internal documentation for the organization where I work as a software engineer. In these cases, perhaps the biggest challenge is encouraging people to actually use the documentation. Often, they do not even know it exists. To help with this, I always try to reference these manuals whenever relevant opportunities arise, such as alignment meetings, technical refinement sessions, workshops, and similar discussions
The Minimalist asking 'why do we need docs?' and then staring blankly at his own code six months later - too real 😂
I know, right? 😂 Hopefully, this is a good lesson to start taking care of documenting the project, even in the form of code comments 😉
As a developer, I can confirm every team has at least one “Jon Snow” and one “Minimalist” 😄
This was funny, painfully accurate, and honestly a great reminder that good documentation is teamwork.
Exactly! 💯 That's why it's so good to have golden ones in the team 💛
As an engineer I am not sure which one I am, but definitely met some heroes described here 😀
Nice first post, keep going on!
Thank you @0xax ! You're definitely our golden boy! 💛😄
This was way too relatable 😂
As someone who relies on docs a lot, thank you for all the behind-the-scenes work you do, Klaudia 😄
Glad to hear that! I hope you meet only the golden ones on your way 💛🤗
Can I be the Mr. Robot of Robots? Is that an acceptable role?
Well, they say you can be whatever you want 😄 So... something in between "Mr. Better" and "Robot"? Quarreling with AI that your version is better? 😄 Or the king of generated content?
Haha funny, this made my day :-)
Happy to hear 😄