Going deeper into Technical Writing

So, it has been 1.5 months since I started in my new role as a Technical Writer for developers-facing documentation (yes, that's why I haven't published a single word). I had many impressions, discoveries, and, a lot of work.?

But let's follow this path step by step.

First, I was lucky that the “Technical Writer” open position for developer-facing documentation was my match (or, for some reason, I was also a match for this position).

Yes, I wrote in the article 'Unveiling the Versality of Technical Writers' (https://www.dhirubhai.net/pulse/unveiling-versatility-technical-writers-svitlana-ivashkiv-5glgf/?trackingId=PlZ1mtoYV%2Bjnsr%2FRgpzzrQ%3D%3D) that, given enough time, experts from various fields can cover their gaps and learn the necessary nuances.?

I am a humanitarian with a good command of language. Not to be immodest, I have a well-honed writing style and can explain complex things in simple language to the target audience. This works great when communicating with users, but developers are of a different caste. I revealed that I have much to learn in this new role, and I'm humbled by the challenge.

They don't need "fluff" in the texts — they want facts, ideally a correctly selected code snippet with a concise explanation of what it does.

I've never done anything like that before. It was a significant challenge for me, as I had to learn a new way of writing and communicating completely different from what I was used to.

One day before starting the work:

We installed Linux (may God bless my husband with health because he definitely has patience). I drifted into another realm with the new OS. I restored, cried, and drifted off again. Where is my best-known Windows? Where is my familiar File Explorer? Windows, dear, you was so convenient (not!). I realized that the computer could "breathe" and operate calmly. Nothing downloads sporadically, just because updates live a life of their own. I cried a bit before going to bed.

My sleep was restless and anxious; Linux chased Windows, shouting: "Give her soul back, she paid her price. You promised!"

First day at the new work:

I opened PyCharm, closed It, opened it again, closed it… My husband showed me what branches are. I nervously made a few laps on the balcony, came back, and, under his careful supervision, started to get familiarized with PyCharm.?

The company provided materials to introduce me to the product. I read a lot.

We started setting up the environment and connecting integrations. My husband managed to calm down (by the way, it was also his first day in a new position but at a different company). I wouldn't have installed and connected so many things by myself. For some reason, I can't specify here due to the NDA and bla-bla-bla (sorry).… But, let’s jump ahead. We spent 3 days configuring the environment with the company's DevOps.

End of the first week at the new work:

I am fantastic, and I am doing great! I work in RST! Well, it's a sort of work…, but at least I create files and learn the syntax.?

I really liked this right away from the first sight. I realized that standard Markdown pales by the side of RST (Sphinx). RST has many more features, and yes, it's not as "polished" as Markdown, but it offers many options, even though you can initially feel overwhelmed by the syntax. But that's okay; I'm gradually getting the hang of it.?

By my first day at the new work, I already knew Markdown, but I understood I could surely "forget" it and start with the Sphinx documentation.

Speaking of the Sphinx documentation, it's written with a sincere dislike for users. It's written poorly, feeble, and quite limited. Maybe I got unlucky with the theme, or it's written for advanced users. Still, my attempts to understand the Sphinx documentation failed spectacularly, so I started to read the standard RST instead. The documentation for RST was remarkably helpful, with engaging examples, reassuring explanations, clear structure, and formatting, although they skipped colorful images (it's a joke). The authors of the documentation worked with dedication and integrity.?

Naturally, I found cheat sheets. And I'm still sneaking glances there, but now I do it without confusion on my face yet with knowledge in my hands!

So, by the end of the first week, I already:

• Have not cried over Linux;
• Worked in a configured environment (and I express my praise once again for my husband's patience, as well as the coordination of work with DevOps);
• Found all the necessary documentation on RST;
• Got the hang of branches and the magic of pull, commit, push, and merge;
• I started learning Jira, the ticket and task system, and workflow (at my previous job, I only needed to dive into it briefly).

The first month at the new work:

The first month of work could be described as exciting and engaging, but it's too long to tell. I can highlight that I completed my first task in the first month.?

Yes, it felt like the birth of a firstborn, probably. Of course, the work was partially independent: I had assistance from teammates, my supervisor did code reviews with me, we had calls, and my team explained where to find necessary snippets, how to outline the logic, and not just write everything haphazardly. And I listened and learned, learned and learned again. Fortunately, Python is quite understandable in terms of syntax (I'm still learning it). Yes, I perceive Python as just another foreign language. This is where my translation skills came in handy, as the approach to learning foreign languages can be easily structured and interpolated to another area.?

What can I highlight at the end of the first month of work?

• I suddenly discovered that most shortcuts from RST work in Google Docs. I laughed and started using them. That simplified my work with documents;
• I learned how to make documentation visually appealing;
• I mastered the text structure in RST;
• I realized what a fantastic product the company is working on. I can't say what it is due to the NDA and other things;
• I felt proud of my involvement in the company's results (even if it was just a tiny, little, nano involvement for now);
• I completed my first task, which was my first document in RST for the developers;
• I wasn't fired for incompetence. (It's just a joke, of course, but there's a truth in every joke.)

Minor and major (acc. to my vision) victories inspired me, and I dove deeper. The next task was to create a definite and detailed document for a separate module. Here, I took notes from videos and composed a document based on the recordings. These were the developers' videos, which provided an in-depth explanation of the entire module. It seems pretty simple (as one might think): just take notes and write. Developers have already explained and even shown everything. But, "it's not that simple."

Every person has their own style of presentation, speed of expressing thoughts, and even their own manner of speaking. Thoughts can get tangled, one can switch from one idea to another in seconds, thoughts can be cut off, and ultimately, thoughts can outpace speech.

I encountered everything while taking notes from the videos. I produced nine separate documents for videos. In the end, all the resulting documents had to be compiled together and structured logically, examples of code had to be found, and from all the flow, only the logic needed to be extracted and "inserted" along with the code examples. I am still trying to define what this type of work is called, but it's engaging. At first, the only thought swirls: "Oh dear Lord, I haven't done this, I'm not sure if I can understand everything." Then, you get into it and start moving through the module's code alongside the video, immersing yourself in its logic. You begin to "read" the code and understand where everything comes from — it's a fantastic experience. The final structured document with examples was quite hefty (90 pages). It's under review now, and I move on to the next task.

So, a month and a half at a new work:

A month and a half of learning, new tasks, and new paths. Yes, I have things to share:

• I've started to understand what the code does (at least to some extent);
• I feel confident with RST;
• I independently created a document for a module;
• I learned to work with videos (gathering information and extracting the logic);
• I mastered searching through the code;
• I've reached the phase of acceptance that technical writing for developers is interesting. I really wanted to work in this area, but I needed a clearer understanding of developers' needs and requirements. I have it now, and this truly changes my approach to the texts.

Plans for the near future:

• To delve into the complex relationship between the front and back end. This understanding is crucial as it empowers me to identify and describe the front-end actions and the corresponding back-end functions or responses. Such knowledge can make me feel more engaged and integral to projects.
• To create a comprehensive document for developers. This document will be based on the BA's document, and my effort will involve deciphering the logic in the BA's papers, finding the corresponding code snippets, structuring the document for the developers, and deleting all unnecessary information.

Responding to the question: "What's the point of this article? Just breathe quietly, keep working, and don't make a blind noise with your sentiments."

The article is written to emphasize that any learning takes time. As described in the article… humanitarians can also learn technical nuances, just as technical experts can master stylistic aspects.

• I was interested in learning the intricacies of the technical side. No, I won't write code, but I want to learn how to read it. Understanding technical concepts, knowledge of text styling, and a clear vision of structure and logic will enhance my competence and become an advantage. However…

Recently, I got a "3-in-1" offer. A company was searching for a technical writer who would understand technical aspects + write excellent user-faced documentation + create content for the website and social media (marketing, SEO). I apologize, but this sounds like a "one-man band." I understand the desire to save money on experts, but one must draw the line somewhere. My wish to master the technical side comes from the fact that I am doing well on the non-technical side, and now I need to improve my knowledge of what's "under the hood." So, I'm not an expert for "a little bit of everything," but marketing and content… is apparently too much.

So, I will write about the results of the probation period.

At least, I was glad to share this information about the gradual switch from translator to technical writer.

It might inspire some of my ex-colleagues or be a solution example because the next financial year is coming.

So, as long as it's still summer, take care of yourselves. Don't overheat, drink water, avoid staying in the sun for too long, and find time to rest.

Have a great day!