Writing Lessons
Today's topic isn't necessarily technical, but it's a skill I think you should cultivate, not only for the benefit of your career but also for the sake of personal development. I've been watching the Chef's Table series on Netflix. The latest series focuses on legendary chefs, including Thomas Keller. It doesn't matter if you don't know who that is. During the episode, the chef made a comment that resonated with me and transcends his expertise in the culinary arts.
Chef Keller said that there are three parts to your career. The first part is when you are struggling to learn everything. The second is focused on mastery. Once you have learned the fundamentals, you refine your skills. The last stage, where Chef Keller places himself —and I suppose I do as well —is the "give back." This is the point at which you need to give back to your industry or community and help plant the seeds for the next generation.
However, for my topic today, it doesn't matter what stage you find yourself. My recommendation is for you to find ways to write about what is important to you. For me, this has been about PowerShell. But, it can be any technical topic.
To clarify, I'm referring to creating content for someone else. I expect many of you are in the first two stages of your PowerShell career. Although you might be in the last stage on a different topic. Writing about a subject is an excellent way to learn and deepen your understanding. The process forces you to organize your thoughts and, in doing so, forces you to fill in any gaps in your knowledge.
The more you write, the more you'll learn. Writing also has the potential to raise your visibility to your employer and your technical community. I'm not suggesting that everything you write has to be made public. Perhaps you have an opportunity to write content that is published privately or internally. Take it.
For public writing, you don't have to write a book. You don't even have to write a blog post. One option, if you don't have a blog, is to set up something using GitHub Pages. This is easy, free, and provides a resource that you can point people to. Or, there are plenty of online sites like 4Sysops and Petri.com that are always looking for fresh content and new authors. At a minimum, your writing could be as simple as a series of well-crafted social media messages.
Know Your Audience
The first step in any writing project is to know your audience. Who are you writing for? What expertise or experience are they bringing to your work? If your writing is highly technical, do you need to review or introduce pre-requisite content? There's nothing wrong with reviewing critical pre-requisite topics. This ensures you and the reader are on the same page, so to speak. It is also possible that the reader doesn't fully understand or misunderstands a prerequisite concept. Your writing provides clarity.
When introducing an acronym or abbreviation, it is a best practice to define it on first use. "Microsoft has recently introduced the next generation of DSC (Desired State Configuration) tools." Once defined, you can use the abbreviation.
Part of this concept is also understanding your goal. What is the purpose of your effort? Why are you writing anything in the first place? Are you trying to achieve a specific goal, such as justifying a cloud migration? Or are you trying to impart knowledge? Consider what expectations or biases the reader will bring to your work. The way they read and process your writing may be different from how you approached writing it.
I encounter this when teaching PowerShell classes. There is always at least one attendee who comes to class with a predetermined bias or agenda, which is an obstacle to their learning. I have to find ways to work around the hurdles. This is obviously much harder to handle when writing. However, it may require including additional introductory material or directly addressing the anticipated challenges.
Documentation
When it comes to writing about technical content, there are two distinct categories, at least in my opinion. When writing, you need to decide which category applies to your work. The first category is documentation. This category plays a vital role in the lives of IT professionals and should not be dismissed. Writing quality documentation is not a trivial task. I am sure I am not the only one to encounter poor documentation.
Documentation isn't intended to teach or express an opinion. It is intended as reference material. It should explain the features and elements of the thing and how to use it. Documentation is not intended to be read from beginning to end. Instead, the reader will most likely jump to sections appropriate to the task or feature they are trying to understand.
Documentation should not be a collection of screenshots. It should clearly describe an element or feature and provide instructions on how to use it. Be careful. I've seen plenty of documentation, presumably hastily written by the developer, that explains something from their perspective. Critical details are omitted or assumed. Remember, you are documenting. This is why technical documentation tends to be dry or even dull. I don't have a problem with that as long as the documentation is clear and complete. You can inject life into your documentation with examples, analogies, and metaphors.
In addition to writing about how the thing works, I would recommend considering adding context. Why would someone need to use this thing? What problem does it solve? How might someone want to use it? These questions will help guide your writing.
Point of View
The other category of writing is what I'll refer to as point of view (POV). This article is an example. You are writing to teach, convey information, share a story, or make a point. All of this is done from a perspective, usually yours. Think of all the blog posts, online articles, or even videos that you've seen. The vast majority of that content is conveyed from the author's POV.
Even though this type of writing might still be on a technical topic, you are now writing documentation. Instead, I recommend you think of telling a story. By that, I mean your writing should have a clear beginning, middle, and end. That may seem obvious, but I've read many blog posts that are mostly "middle" or "middle-end".
Take the time to lay the groundwork. Introduce the characters. Just as a good piece of fiction has exposition, your technical writing can also have exposition. Perhaps you should provide background information or define some key terms. Tell the reader what you are going to write about and why.
The middle is the heart of your writing. If you are writing about a technical topic, write about it in a logical order. If I'm writing about PowerShell functions, I first need to write about scope. Don't assume the reader knows everything you do. That's probably why they are reading your work in the first place. Don't be afraid to cover a topic because you think it's "too basic" or "everyone already knows this," because not everyone does.
Your writing should have an arc. You should have a clear idea of where you want to take the reader and the best way to get them there.
After you've reached the goal, the "end" stage doesn't have to be extensive. Repeat and reinforce key concepts. Perhaps consider providing the reader with a "call to action". There is an adage in comedy that I learned in my theater days, which has always stuck with me. "Tell them you're going to tell them [a joke], tell them, tell them you told them so." This is the same beginning, middle, and end construct that you should apply to your writing.
Tell me a story that will keep me engaged. You could write about an ogre or Hyper-V. Structurally and conceptually, there is no difference. All that changes are the words.
Summary
If you aren't already doing it, I hope you'll consider taking up writing. You don't have to write a 5,000-word article. For reference, this article is about 1500 words. Start small. I also recommend using a service like Grammarly. Or use a tool that provides grammar and spell-checking. I also caution you about AI-generated content. I don't have an issue if you need AI to help you rewrite a paragraph or use it as a brainstorming tool. However, be very cautious about using AI to write for you. That defeats the whole purpose. I can see a case for AI-generated documentation. But an AI is not you. If you are writing a POV piece, you want the writing to capture your voice, not the AI.
Yes, writing will be hard at first. But the more you do it, the easier it will become.
If you have a public writing outlet you'd like to share, please feel free to leave a link in the comments section online.
Good luck!
(c) 2022-2025 JDH Information Technology Solutions, Inc. - all rights reserved
I have been long wanting to write good technical documentation or writing helpful documentation at work .I always thought i am not a good writer :) or i dont have the skill :)<br /> After reading this article i have some confidence to start and give it a try .
Thanks for sharing your wisdom :) ..
I started at a very young age in computers. After 40+ years I have found my father's method of learning to work very well. He said "See one, do one, show one". The idea being you see it done by others, do it yourself, then show someone else how to do it. Your post reminds me of the third step where you are trying to pass on the knowledge thereby reinforcing your own understanding. Great post!