Came across and liked this web architecture basics video, so that’s our Tech Byte for today!
GitHub is a popular version control and collaboration. In my experience, learning GitHub can add tremendous value to your profile as a technical writer. GitHub enables you to contribute to open source projects and build your documentation profile. It also demonstrates your collaboration skills (working with developers and other team members), knowledge about version control, and overall technological literacy and comfort.
Getting started with GitHub is fairly easy. Follow the official guide to create your own repository!
And watch this video:
In January, we focused on building our tech skillset:
Now that you have familiarized yourself with the basic architecture and programming of apps and websites, you might want to scale your app, host it on a cloud platform, and deploy it on a orchestration platforms such as containers. Sounds daunting? That’s because it is.
Yet that is what deeply-technical writers do at their everyday jobs. The technologically complex products that our companies develop do not work in isolation. These products are used in an even more technologically complex environment. And to document these products well, it is imperative to understand the ecosystem they are used in. For instance, to document CockroachDB, me and my fellow technical writers at Cockroach Labs need to learn how to deploy CockroachDB on AWS, Google Cloud, Azure, and how to use orchestration technologies such as Kubernetes and Docker. And we have to evolve our knowledge in parallel with the evolving technological landscape.
This can definitely seem daunting for a beginner tech writer, and rightly so. But the important thing to remember is you can never familiarize yourself with all the technology out there – no one can. What you can do, however, is become comfortable with the technology and its ever-evolving nature. In my experience, learning how to learn is the mandatory skill for a technologically-literate writer.
To that end, let’s familiarize ourselves with the common tech jargon that forms the everyday vernacular of developers. Understanding these technical concepts will help you to communicate better with the developers and take on technically challenging documentation projects with confidence. This month’s resources will discuss:
- How does the internet work? (Scheduled for 02/09/2018)
- Cloud computing for beginners (What is cloud computing? Introduction to AWS and DigitalOcean) (Scheduled for 02/16/2018)
- Containers for beginners (What are containers? Introduction to Kubernetes) (Scheduled for 02/23/2018)
In the previous post, I shared a resource for Python, which is an excellent language for server-side programming. This week, I want to share a resource for the web client-side programming. This week’s resource is HTML for absolute beginners. It is an hour-long video that shows you how to build a web page from scratch. I love that it’s so hands-on and builds up from the basics of HTML programming. Check out the video here:
Bonus tip: Learning HTML makes it very easy to learn authoring languages such as XML and Markdown.
On the topic of how “technical” should technical writers need to be, the Technical Communication (TC) community is divided into two camps: Those who think it is absolutely essential to be tech-savvy to be a good technical writer, and those who think being too tech-savvy is actually a handicap for a technical writer. I belong to the camp that says being technical is a blessing for your career.
The camp you end up in depends on the product and company you work at and your end audience. If the product is a UI-based product, then yes, being technical is not a requirement. You need to explain the terminology and workflows, which does not require technological knowledge. But in today’s usability-focused world, products are getting intuitive and not needing extensive documentation. And to simplify the user-experience, the complexity is moved to the backend. With the rise of modular software architectures and plug-and-play software modules, the need to good technical writers is increasing in the developer documentation arena. Developers now don’t need to tell users how to use the products; instead, they need to tell other developers how to integrate the products with their own. And this is where, in my opinion, the lucrative opportunities for technical writers lie.
My experience so far validates my belief. Granted, my academic background is in engineering, so I am naturally inclined to the technical side of things. However, I think even if I was not an engineer, I would still have learned all things technical that I possibly could. Let me show you how “being technical” has helped me in my career so far:
I started my career as a VLSI engineer at Wipro. There, I was asked to document the Application Notes for the Integrated Circuits we were designing, and thus began my love affair with technical writing. After a year, I switched fields and moved to Symantec as a Technical Writer. At Symantec, I learned the on-the-job skills required for good technical writing. But the job wasn’t technical enough to retain my interest and the engineer in me started cribbing about it. So I moved to Druva as the Engineering Technical Writer and this proved to be the inflection point in my career. At Druva, I documented the software architecture and design of our products for internal developers. I reported to the VP of Engineering and worked closely with the CTO and the developers. The documents I created helped developers understand the overall architecture of the product, know what their colleagues were working on, learn what design decisions were made and why, and helped them better collaborate with their peers. Also, they were relieved that they didn’t have to write the design docs anymore. At most, they would have to write a rough draft and I would take it from there. As a result, I became a valued and highly visible member of the Engineering team. The position opened up several growth avenues for me, one of which led me to the MS in Technical Communication program at Missouri S&T. My work helped me develop an amazing rapport with our CTO – he offered me a summer internship in the California office, which was later extended to a remote part-time internship that lasted throughout my second year at Missouri S&T.
In the last semester of my grad program, I started looking for jobs. I didn’t want to go back to California. This time, my heart was set on New York. As an international student, I knew I would have to prove my worth for a company to take a chance on me. And the way to do that was to build my portfolio. So I researched open source projects where I could contribute documentation and build my portfolio. I came across an interesting project – CourseWorld – and started contributing software design docs to the project. This project helped me demonstrate not only my ability to understand and document technology, but also my knowledge of GitHub and online collaboration tools. In short, it helped me “show, don’t tell”. And it worked! I got interview calls from exciting startups for deeply technical positions. One of the calls that got me super-excited was from Cockroach Labs. After an intense interviewing day, I was hired as a Senior Technical Writer at the New York office and offered a six-figure salary. So you can see why I am biased to being more technical 🙂
Being technical has helped me leap through my career. It has opened up avenues of career growth that I didn’t know existed. And honestly, it’s just fun to dive into the inner workings of a product and understand how the magic happens.
Update: I made a video to discuss how tech writers can work on becoming more tech-savvy. Check it out:
If you have questions, suggestions, or blog post requests, drop me a line at firstname.lastname@example.org