tag:blogger.com,1999:blog-48315365639355124502024-03-12T23:31:39.640-07:00The PlaceholderWater cooler talk for tech writers.William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.comBlogger61125tag:blogger.com,1999:blog-4831536563935512450.post-36608306134790790992024-01-05T10:51:00.000-08:002024-01-05T17:18:12.463-08:00When you Doc as Code<p>What is doc as code? Doc as code is basically two things. One, it's creating documentation with the same tools as you would use to create code. Two, it's using similar methods of creating, versioning, and publishing documentation as you would with code. </p><p>What do I think about this? Short answer is context. If you're creating or editing material in a software environment that uses <a href="https://asana.com/resources/agile-methodology">Agile methodology</a>, then you should doc as code. Otherwise, I wouldn't worry about it. If you're in this context, I'll give you a few, brief reasons why you should doc as code.</p><h4 style="text-align: left;">Save Costs</h4><div>The first and foremost why you should doc as code is to save costs. Tools, licensing, even training on how to use tools all cost money. It also costs time to maintain and invest on different tool sets. If you're using the same tool to create code and documentation, you can save on both. No further explanation needed. </div><h4 style="text-align: left;">Easier to Build Bridges</h4><div>If you're using the same tool as your Subject Matter Expert (SME), it's easier to build bridges to create documentation. If you're using the same tool(s), it's easier to collaborate together on documentation. This doesn't mean you have to learn to code. (But it might help to know a little bit.) In some ways, using the same tools and releasing documentation the same way as code is like you're speaking the same language as your SME.</div><h4 style="text-align: left;">More Unified Experience</h4><div>If you doc as code, then the release of software and documentation is much easier. The obstacle of getting your documentation in a certain format, so it goes with the software release is no longer an issue. You just have to make sure you and your SMEs are working in sync to make sure the documentation reflect what's in the code and vice versa. And that can be challenge in itself, so why would have other unnecessary issues to prevent this from happening.</div><div><br></div><div>To find out more about doc as code, check out these resources:</div><p><a href="https://www.writethedocs.org/guide/docs-as-code/">https://www.writethedocs.org/guide/docs-as-code/</a></p><p><a href="https://www.gitbook.com/blog/what-is-docs-as-code">https://www.gitbook.com/blog/what-is-docs-as-code</a></p><p><a href="https://github.com/readme/guides/code-as-documentation">https://github.com/readme/guides/code-as-documentation</a></p><p><br></p><p><br></p><p><br></p>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-52500361316841807882023-12-08T12:26:00.001-08:002023-12-08T13:05:38.379-08:00Grateful For This BlogI mentioned this <a href="http://www.williammcfadden.com/2022/07/the-moment.html?m=1">before</a>, but sometimes it's worth restating. No matter how much blood, sweat, and tears we pour onto technical documentation, <b>it's not ours. </b>Those who of us who are technical writers are just hired wordsmiths for someone's else product. They can take the credit for it, even though we have labored on creating or editing clear documentation that presents a message for their audience. Without us, their customers would probably be confused on they offer or how to work their stuff. (Now, there's really bad documentation out there that's confusing that does this anyway. But that's another discussion for another day.)<div><br></div><div>When I first became a technical writer, the most stinging part initially was I had no byline. The document's byline was the company's. But I realized over time: <b>It's not about me. </b>It's about the company I represent and their customer. God has continued to use technical writing to show me of this fact. </div><div><br></div><div>I would be lying to say I'm totally okay with this fact what we write isn't ours. But I can also say I have embraced this fact and it continues to make me a better writer. I realize what I do isn't about me. Sounds like a contradiction. It's just a lifelong process of accepting this. I'll let you decide whether I am contradicting myself.</div><div><br></div><div>I have this blog because it's something I can call my own. I don't care if it gets a lot of traffic. I don't care to be famous. It's overrated anyway. I just wanted something where I can showcase my writing style. I am grateful for it. I also use it to help those who are on their journey with technical writing or even just writing in general. We are all writers, regardless of our stripes.</div><div><br></div><div>But ultimately, nothing I write is my own, not even this blog, my novel, or anything else I write. It all belongs to God. What I do should glorify Him. Technical writing just helped me see this eventually.</div><div><br></div><div><i>“(A Psalm of David.) The earth is the LORD'S, and the fulness thereof; the world, and they that dwell therein.” -- </i>Psalm 24:1 KJV</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-21893387254319227692023-11-24T11:01:00.000-08:002023-11-28T08:16:14.666-08:00Not All Writers Are Equal...And That's Okay<p>Different kinds of literature are everywhere. That's just a fact! Whether it's a fantasy or sci-fi novel, historical fiction, a book on historical events, biography, memoir, or even ad copy, UX writing, video game writing, interactive fiction, blog posts, reviews, or a news article, we see different forms of written work out there. So what's the point in stating the obvious? </p><p>The obvious is just because you're a writer doesn't mean you can write every form out there. I suppose you could. But are you going to excel at it? Are you truly passionate about a particular subject or genre? Do you have previous expertise in a particular field of knowledge or at least willing to learn that field? Or, is this for a paycheck or creating a vanity project? Any writer who is serious should honestly ask themselves these questions.</p><p>To be fair, there are some writers who do great writing at different genres. God bless them for having this ability. Writers, such as CS Lewis, who wrote both non-fiction and fiction was great at what he did. I have been blessed from what he wrote. And writers, such as Harry Turtledove, has been successful creating many different types of novels, especially alternative history and fantasy. (I have yet to read his alternative history stuff, but I would like to. I've only read his fantasy work thus far.) </p><p>And, there are writers who write for a hybrid of genres. For example, the technical copywriter has to dance between writing engaging marketing copy and explaining technical information clearly. Talk about a feat!</p><p>For others, such as myself, I excel at one area–technical writing. I don't consider myself that good. I just simply do my best to create clear, accurate, easy-to-follow technical documentation. (I have written a novel, but it seems I excel as a technical writer instead. Whether I write another novel, well, that's to be determined.) For me, creating technical documentation is as natural as breathing. Even though it's still hard work, after all these years, it's a labor of love. I like guiding people through complex topics or helping them learn how to do something. </p><p>Not everyone wants to do what I do and that's okay. I don't picture myself writing ad copy, alternative history, high fantasy, or even a treatise either. And that's okay too. </p><p>I let the other writers who are more skillful than I do that. As much as I love to write, I also love to read and appreciate a good book. If I'm able to incorporate elements of their work into my niche, then great. If not, I can just appreciate at what they do, the story they're telling, and learn from them.</p><p>God has created a big enough world for us to live in and includes us writers. We don't need to feel squished out by other writers or have to write every form there is out there. We don't need to sound the same. Each writer develops a particular voice over time. I can't explain this. It just happens the more you do this. </p><p>If you're a writer, or you're trying to get into writing, ask yourself these things: what things interest you, where do you feel no one is writing about, or what needs can I fill? If you were to ask me, I would tell you to pray about this and see where God leads you. If you take the first step, or the next step, as a writer with this mindset of asking yourself this, you'll find where you need to go.</p><p>Not all of us writers are equal and that's okay.</p>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-1393041052068994672023-10-31T09:54:00.000-07:002023-10-31T09:54:06.191-07:00Some Cliches Still Have PowerWith writing, especially technical writing, we're supposed to get rid of cliches. Why? Cliches have been so overused where they lost meaning or power. Yet, if we're honest, we communicate in cliches at times because it best captures something we're trying to say.<div><br></div><div>The cliche "the pen is mightier than the sword" is true because written works have brought far more change in this world, or destruction in some cases, than any armed revolution or army could ever do.</div><div><br></div><div>Even though I'm just a technical writer, I feel humbled to be a part of a craft that has potential to change the world.</div><div><br></div><div><b>Not Just Halloween </b></div><div><br></div><div>Today, is Halloween also known as <a href="https://blogs.loc.gov/headlinesandheroes/2021/10/the-origins-of-halloween-traditions/">All Hallows Eve</a>. However, on this same day, it's </div><a href="https://www.ligonier.org/learn/articles/what-reformation-day-all-about">Protestant Reformation Day</a>.<div><br></div><div><a href="https://reasonabletheology.org/the-life-of-martin-luther-a-brief-biography-of-the-reformer/">Martin Luther</a>, an Augustinian monk, saw the abuses of the Church in his day, where it was more about money and power than about love and grace of Jesus Christ. He was so disgusted that he had to get the word out about these abuses by posting his <a href="https://www.luther.de/en/95thesen.html">95 theses</a> on the door of the Wittenberg Castle Church.</div><div><br></div><div>And from there, whether for good or for ill, Martin Luther altered the course of the Western Christian Church, Europe, and eventually good parts of this world. (If you want to read an in-depth biography about Martin Luther, I recommend Derek Wilson's <u><a href="https://www.amazon.com/Out-Storm-Life-Martin-Luther/dp/0091800013?ref=d6k_applink_bb_dls&dplnkId=c30c795d-5120-4ac4-8568-1b43d9a7b088">Out of the Storm</a></u>.)</div><div><br></div><div>Now I'm aware that Martin Luther wasn't perfect. They were things that he said that I'm still scratching my head to this day. But people and their written work don't have to be perfect to affect the world.</div><div><br></div><div>When the time and conditions are right, written works are the sparks that set the blaze of change to consume the world.</div><div><br></div><div><b>The Book that Affects Change</b></div><div><br></div><div>But I would be remiss if I didn't mention the Greatest Written Work that has permanently changed the world, the Bible. </div><div><br></div><div>The Bible is the most controversial book known, yet it still changes lives. Empires have fallen. Nations have changed and gotten liberated from their oppressors. Slaves have been set free. People have died over it, especially those who want to get it in the hands of the common people. It has been demonized, mocked, and has polarized people. Wars have been waged over it. Sadly, it has been the most abused written work to justify evil behavior and hatred. Yet, the Bible has been used to stand for justice, liberty, and love. The Bible has the power to affect the world. God said this about His Word:</div><div><br></div><div>Isaiah 55:11 ESV
</div><div><i>"...so shall my word be that goes out from my mouth; it shall not return to me empty, but it shall accomplish that which I purpose, and shall succeed in the thing for which I sent it."</i></div><div>
</div><div><br></div><div>What is the Bible? In a nutshell, it's God's story of salvation for humanity and Creation. After He created the world and people and they rebelled against Him (Genesis 1-3), He set a plan to redeem what was lost back to Himself. If you keep these following verses in mind till you get to the end of the Bible, you will see how God's plan of salvation comes together:</div><div><br></div><div>Genesis 3:14-15 ESV
</div><div><br></div><div><i>"The Lord God said to the serpent, “Because you have done this, cursed are you above all livestock and above all beasts of the field; on your belly you shall go, and dust you shall eat all the days of your life. I will put enmity between you and the woman, and between your offspring and her</i> <i>offspring; he shall bruise your head, and you shall bruise his heel.”</i></div><div><br></div><div>The Bible is the written work that has changed and continues to change my life. If you want to know the Bible for yourself, then check it too. You won't be the same.</div><div><br></div><div>Thank you for stopping by. Happy Reformation Day! Happy Halloween! God bless!</div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-84709306495205814522023-10-26T16:41:00.000-07:002023-10-26T16:41:42.683-07:00Simple yet deep (or difficult)When I was choosing a vocation, I just want to do something simple, yet take a lifetime to grow in it. Writing seem to fit. Writing is actually hard, even if you want to get good at it. I don't claim I'm a good writer. I just happen to enjoy it, and God continues to bless me with a career in technical writing.<div><br></div><div>Writing is not perfection, which I think is the core problem of writer's block, it's about the process. And the process is one that I enjoy and find it a privilege to continue be a part of.</div><div><br></div><div>Simple, yet deep (or difficult) is the essence of the writing craft. It sounds like I'm contradicting myself. But, hang on. If you want to be a writer, you just write! Don't think about it! Don't talk about it. Just do it! That was the best advice I got when I first started my writing journey. It's been difficult along the way. But to start was simply just to commit my first word on paper (or screen) and go from there. The deep, many times difficult, is where you continue to grow and improve your craft. The initial draft is easy because it can be poor, disjointed writing. (That's not to say, it's always easy. I continue to struggle with an initial draft. But it doesn't have to be hard.) The hard part is the rewrite and edits to take your writing to the next level. </div><div><br></div><div>I guess we can say the writing craft is a paradox. And it's a paradox worth diving into. It takes tenacity to swim through this paradox. When coming out on the other side to see the finished product, it was worth the effort.</div><div><br></div><div>Simple enough to start, yet deep enough (or difficult enough) to develop. That's writing in a nutshell. Or if you're like me, that's technical writing. Thank you for stopping by. God bless.</div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-40836944415468142622023-09-14T17:42:00.048-07:002023-09-15T12:13:49.013-07:00When you don't have all the piecesWhen you create documentation, there are three fundamental questions you need to ask.<div><br></div><div>1. What is the thing you're trying to document?</div><div>2. What kind of document are you writing?</div><div>3. Who is the audience for this document?</div><div><br></div><div>If you get answers to these questions and find the key Subject Matter Experts (SMEs), you're on your way to creating good documentation. But let's be honest with ourselves, even with this information, there's a good chance that you'll still have missing pieces. What do you do then? </div><div><br></div><div>If you're in a circumstance, where you can test the product, say software or API calls, then you can probably fill some of the missing information. But not all technical writing circumstances are the same. Sometimes, we're detached from the subject we're writing about because we're not able to test a product. Going on a limb here, say nuclear technology. It doesn't have to be this extreme. But it could be just simply no way of testing out your subject or product. So what do you then?</div><div><br></div><div>One thing you can do is be persistent. As you talk to the SMEs, ask your questions along the lines of the fundamental questions you've asked initially. When SMEs are stumped from your questions, you can ask them who would know. They might direct you to another point of contact or get back to you if they need to dig into this. In any case, finding the missing information for a documentation isn't impossible. It just requires persistent. </div><div><br></div><div>The worst that can happen with documentation, is that you can't write it, because the information doesn't exist and maybe the subject just a concept for now. And that's a planning issue beyond the scope of your responsibilities. Aside from this, if you're persistent you can find the missing information.</div><div><br></div><div>It reminds of the game Chrono Trigger with mysterious gray chests scattered throughout in different places and time. When you try open them, it would play <a href="https://www.youtube.com/watch?v=WMsgUQbQN7o">a song</a> and a dialog box tells you a mysterious force is keeping it locked. You can still play the game but it seems like something's missing when you can't open these chests. These chests stay locked until you charge up Marle's perdant and that's when you can open these mysterious chests. </div><div><br></div><div>Like the way you need to charge up Marle's pendant to unlock these chests, you just need to find that piece of information or point of contact that help links the missing pieces together. Creating documents can be an interesting quest.</div><div><br></div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-3858833213273354782023-05-19T11:42:00.061-07:002023-05-22T17:32:28.546-07:00QA Your Docs: Final but often rushed step<div><br /></div>Once you've written the docs, it's time to release. Right? No.<div><br /></div><div>Other Technical Writer: But I double-checked the text and the graphics to make sure it looks good. </div><div><br /></div><div>Me: That's great. You looked at the docs and made the edits. Editing is step 4 in the general writing process. Every step in the writing process is crucial. But did you QA the docs? </div><div><br /></div><div>Other Technical Writer: QA? </div><div><br /></div><div>Me: Yes, did you QA?<div><br /></div><div>Other Technical Writer: What do you mean by that? Do you mean I sent the doc to QA? </div><div><br /></div><div>Me: Well, you can do that and probably should if you have QA people. But did you QA the doc yourself, especially if you have the ability to do so. </div><div><br /></div><div>Other Technical Writer: Well, how do you do I that? </div><div><br /></div><div>Me: QAing your documents just means check to make sure the steps you wrote is matching the product is doing. In other words, does your document correspond to reality?</div><div><br /></div><div><b>Often Overlooked Step</b></div><div><br /></div><div>If we simply take the time and check to make sure the document is actually saying what the product is doing, then it might avoid dissatisfaction from our customers. How beyond annoying is it when the instructions are not only confusing but also don't correspond to the actions or parts of the product? This is probably why many chuck the instructions and try to figure it themselves. For a lot of things, someone can do this just fine. And the instructions are just stupid and useless. But what if those instructions are critical? And, if they try to do this themselves, they and others might get hurt–or killed–because of poor documentation. </div><div><br /></div><div>Instead of rushing things and slapping instructions together, let's simply take a little extra time to make sure the documents accurately portray the product. Faster isn't always better. It reminds me of this Scripture, especially the latter part of the verse:</div><div><br /></div><div>"It isn’t good to have zeal without knowledge, nor being hasty with one’s feet and missing the way." -- Proverbs 19:2 WEB</div><div><br /></div><div>A well written but inaccurate document is completely useless and should be tossed in the trash. A useful document has both accurate information and simple writing to clearly explain it.</div><div><br /></div><div><b>How Do We QA a Document?</b></div><div><b><br /></b></div><div>To<b> </b>QA a document, just walkthrough the document to verify what it says matches what the product actually does. When it doesn't, then fix the language or pictures until you go to the end.</div></div><div><br /></div><div>If you feel it's too daunting to go through the entire document in one go, then you can QA a section after you finished writing and editing it. You can also go through the document in chunks until you're done. It doesn't matter how you do it. What matters is that you QA the document before you release it.</div><div><br /></div><div>If we take this final, but needed, step then we won't miss our way. If someone is preventing you from taking this step, push back if you can and tell them to wait until you're done. (Of course, the product and its documentation should go out the same time.)</div><div><br /></div><div>It's better to take our time and put out documentation at a reasonable time, then rush it out the door and you'll have to deal with a bunch of problems after.</div><div><br /></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-5908523310172087012023-04-20T14:07:00.002-07:002023-04-20T15:05:02.134-07:00More Thinking, But Don't Overthink<p>What if we thought more before we said or wrote anything? I like what Warren Buffet said about how <a href="https://www.goodreads.com/quotes/432412-i-insist-on-a-lot-of-time-being-spent-almost#:~:text=Learn%20more)-,%E2%80%9CI%20insist%20on%20a%20lot%20of%20time%20being%20spent%2C%20almost,than%20most%20people%20in%20business." target="_blank">spends his time thinking</a>. This sitting and thinking can come in handy as technical writers.</p><p>Before we create documentation or in the process of creating one, it might help to stop and think things through. (This will especially be handy if you have a product to play with.) We might get clarity as we walk through a mental journey to overcome some huddles. </p><h3 style="text-align: left;"><b>Save Time and Effort</b></h3><p>Thinking more might save you time and effort on documentation. Rather than fuddling around where you might end up deleting either half the documentation or the whole thing, why not think things through before you write? Jotting some quick notes can help you see where you need to go. (While I believe deleting what you wrote previously is a part of the writing process, there is such a thing as overediting, which I think is a part of overthinking, which I will get into in a bit.) Thinking can help you create a map of where you want to go or prevent taking unneeded steps. </p><p>So, if we were documenting a product and we had it in our head initially to create one giant document, but then as you think it over, it turns out it would be better to have a series of smaller documents. Or, let's say you thought at first you need multiple documents but you realize only need one document. Or finally, the product is so self-explanatory, it doesn't need documentation at all, so you can focus your efforts elsewhere. </p><p>Thinking things through can help us with this, rather making rash judgments where we'll regret this later. We only have so much time in our lives, so we need to be prudent with what we do.</p><h3 style="text-align: left;">Writing is Thinking–Probably Not</h3><p>Some might contend that "writing is thinking." I see what they're saying. I agree with this to a point, but in the end I have to disagree. Writing and thinking are two different things. Thinking is a mental process in your head. Writing is a creative process that shows itself in print, audio, or screen. Thinking may help you get ready for writing but it's not writing. If you think otherwise, that's fine. We can agree to disagree.</p><h3 style="text-align: left;">Don't Overthink, Just Write</h3><p>Just like you can overwrite or overedit something, you can overthink something. Overthinking is bad. Like over-engineered or overwritten work, it can be confusing at best, where you have too many caveats, complexities, or features. At worst, it can lead you to a mental paralysis where you can't write anything at at all.<br /></p><p>After thinking something through, it's time for you to write and let the chips fall where they may. When it comes to writing, I agree with Ray Bradbury. I like what he said about <a href="https://www.goodreads.com/quotes/9123-don-t-think-thinking-is-the-enemy-of-creativity-it-s-self-conscious" target="_blank">writing</a>. In context, he was referring to creative writing. But I think we can apply this to technical writing. </p><p>I have seen other technical writers, and I've experienced this myself, paralyzed to create documentation because we overthought stuff. We were trying to take too many things into account. When we commit to writing, we just need to need write it out, refine it, and publish it. Worst case scenario is we need to revise the documentation. Revising documentation is a part of life as a technical writing. This is especially true if you write for software applications, where updates are the norm.</p><p>But first, what if we sat and thought carefully, without overthinking, through things before we did anything? I wonder how life would be?</p>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-32261345623795191732023-03-30T13:49:00.003-07:002023-03-30T13:50:48.623-07:00Be thorough, not Pedantic<p>As technical writers, we must be <span style="background-color: white; color: #212529; font-family: "Playfair Display", serif; font-variant-ligatures: no-common-ligatures;">thorough when we create or edit documentation. If we're not, then we might present shoddy, confusing, murky, or incomplete information to our audience. But being thorough doesn't mean you should be <a href="https://www.merriam-webster.com/dictionary/pedantic">pedantic</a>. </span></p><p><span style="background-color: white; color: #212529; font-family: "Playfair Display", serif; font-variant-ligatures: no-common-ligatures;">Pedantism is annoying at best and destroys relationships at worst. It's unnecessary, short sided, and stupid.</span></p><p><span style="background-color: white;">But what's the difference between being thorough versus being pedantic? For us, being thorough is carefully making sure the documentation is clear and helpful for our audience. Or when you're dealing with SMEs, you ask good or the right questions to get the information you need. But being pedantic is pointing out, or if we're being honest with ourselves, picking on small details that don't matter. </span></p><p>Does it compromise the clarity of the documentation? If not, let it go. But if one wants to insist these details are important to point out, then think carefully and honestly. Are they important? Seriously, are they?<span style="background-color: white;"><br /></span></p><p><span style="background-color: white;">Or, if there's a small error or limitation and you can safely assume (it's okay to assume sometimes) most people are going to figure it out, then let it go. </span></p><p><span style="background-color: white;">How about speaking with others? Are you going to point out to small inaccuracies in their word choices because it's not to your liking?</span></p><p><span style="background-color: white;">One of the worse forms of pedantism to me is when someone corrects someone's grammar or pronouncing when they speak. Why?! Did they ask for help speaking? What are you doing other than showing how smart you are and showing how stupid you think someone is? Are you that thin skinned that you can't possibly hear an imperfection? If you understand someone's point clearly, then why do that. All it does is sour relationships. If you want to be a successful technical writer, it goes beyond great writing, grammar, and editing skills. It's also about building great relationships. Without it, you might have nothing to document.</span></p><p><span style="background-color: white;">Don't think I'm okay with bad grammar. I just save correcting and improving the grammar for documentation. And even then, the grammar rules we uphold aren't as ironclad as you think. (While these rules give structure and meaning to any language, they aren't infallible. Sometimes, these grammar rules are fake.) Don't believe me. Look it up. </span></p><p><span style="background-color: white;">If given the choice, I rather take a clear sentence that they may not be perfect grammatically, than one that's "grammatically" correct yet clunky in its explanation.</span></p><p>Guess what? No matter what you do, no documentation is perfect. No tool is perfect. No one is perfect. Nothing except for God is perfect. It's an exercise in futility if you strive for that. Instead, strive for clarity, technical accuracy, and good document design the best you can. The rest will take care of itself. If you need to make improvements, then so be it. </p><p>Besides, you wouldn't want perfection because there would no longer be any innovation, whether on the subject you're documenting or documentation itself. Think where that ends up, if there's nothing to improve because of perfection.</p><p><span style="background-color: white;">Pedantics, like legalists, focus on the minute details but not the big picture. It reminds me what Jesus said when He rightly rebuked the Pharisees for their pedantry. Check it <a href="https://www.biblegateway.com/passage/?search=Matthew+15%3A1-20&version=NIV">out</a>. </span></p><p><span style="background-color: white;">Also, pedantics may like to impart their "wisdom" on others. But they don't like when someone else does it to them. If a pedantic person is honest, then they don't like that. It reminds me of what Jesus said here about the measure in judging people. Check out what He says </span><a href="https://www.biblegateway.com/passage/?search=Matthew+7%3A2&version=NIV">here</a><span style="background-color: white;">. If anyone wants to be pedantic, then they'd better be prepared for other pedantics to correct them. </span></p><p><span style="background-color: white;">If not, why carry the weight of pedantism around? It's not just a burden others, it's also a burden on yourself. </span><span style="background-color: white;">Dump pedantism into the metaphorical ocean. (Don't actually dump anything into the ocean. Seriously. Don't. Let's keep it clean, if we can.)</span><span style="background-color: white;"> Free yourself from it. If you don't, it can hinder you from growing as a technical writer.</span></p><p><span style="background-color: white;">Now, it would be hypocritical of me to lance pedantism from a high holy horse without admitting my own faults. </span><span style="background-color: white;">I've been guilty of having some pedantic tendencies in the past. Mine was trying to absolutely uphold style guide conventions, but I didn't take context into account. While I still think style guide rules and convention are great, they're not absolute. </span><span style="background-color: white;">I'll also still uphold style guide conventions, but if a sentence sounds clearer and more natural and it "breaks" with convention, then I will choose this sentence over some arbitrary rule. </span><span style="background-color: white;">My focus is</span> on the big picture: Creating clear and helpful documentation for the intended audience.</p><p>By trying to get away from these tendencies, it's helping me to continue to grow as a technical writer. I'm able to work with liberty and confidence. And my relationships with SMEs have also improved over the years.</p><p><span style="background-color: white;">Life is too short to be pedantic. Focus on the big picture. Is the documentation clear? </span><span style="background-color: white;">Is it helpful?</span><span style="background-color: white;"> Writing in a</span><span style="background-color: white;">ctive voice goes a long way with this. Is it for the intended audience? Building genuine and good relationships with SMEs will help you understand your audience. Do it with a smile and laugh.</span></p><p><span style="background-color: white;">Don't let the minutest of details distract you from that, especially the ones that don't matter in the big picture. When it comes to pedantism</span><span style="background-color: white;">, that adage "the devil is in the details" applies. So, let's prevent the devilish details from winning out.</span></p><p><span style="background-color: white;">Be thorough, not pedantic.</span></p>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-88441193199342137612023-03-08T15:14:00.000-08:002023-03-08T18:01:24.539-08:00Show, Not Tell–Bring Documentation to LifeAs you've pursued the writing craft, you may have heard or read the following:<div><br></div><div>"When you write, show not tell."</div><div><br></div><div>This is great advice. <a href="https://self-publishingschool.com/show-dont-tell-writing/" rel="nofollow" target="_blank">Showing rather than telling</a> brings life to your writing. I struggled with this when I first started out. I still struggle at times. But what does it mean to show rather than tell? Let me attempt to give an example:</div><div><br></div><div><b>Tell: </b>Toby went across the rocky, cratered terrain on his rover to get to the city.</div><div><br></div><div>Nothing wrong with this sentence. It describes what's Toby is doing. And there's nothing wrong with just telling your readers what's going on. For me, it's simplest approach. But if you do this with every single sentence, your writing might become flat.</div><div><br></div><div><b>Show</b>: "Uoof," Toby cried as he went over a rock. "This is no easy cruise. Whoa!" Toby sharply turned the steering wheel of his rover to the left to avoid falling into a crater. "That was close! Just a few more miles before I get through this rough patch. I see town up ahead."</div><div><br></div><div>Here, showing adds dimension to what Toby's doing. It's more than just writing more sentences and adding dialogue. Far from that. It's about painting an in-depth picture, especially if it helps the story along. </div><div><br></div><div>But with all great pieces of advice, we can take it to an extreme. If we show everything, then we can get an overwritten mess, where you might overwhelm or confuse readers. You might end up with written pictures without any context to link them. Narration is telling a story, regardless how you look at it. Knowing where to show and where to just tell is tough and can only come through practice and time. <b>The key with showing is using it where it better communicates you're trying to say. </b></div><div><br></div><div><b>Showing in Technical Documentation </b></div><div><br></div><div>One of the advantages with technical writing versus other styles is showing versus telling is easier to do. I'll explain how. Rather than crafting a narrative like the example above, you can use screenshots and other examples in certain parts of document. </div><div><br></div><div>If a flowchart or a screenshots succinctly explains a concept or an action better than writing out paragraphs of text, then use the picture. The cliché "a picture is worth a 1000 words" is true in technical writing. </div><div><br></div><div>If you're writing something like API documentation, then showing code examples and call responses will help communicate your point across. I would venture to say with API documentation, code examples and responses are more important than the writing itself. So, showing is crucial. For an example, see <a href="https://developer.squareup.com/docs/orders-api/create-orders" rel="nofollow" target="_blank">one from Square</a>.</div><div><br></div><div>I would include hyperlinks in showing rather than telling, if they better showcase what you're trying to say. </div><div><br></div><div>But you don't want to place screenshots, code examples, or hyperlinks just for the sake of doing it. You risk having a bunch of examples without context. Doing so, might confuse and overwhelm your audiences. You want to place examples in your documentation because they better clarify information you're trying to convey. <b>Knowing where to place visual examples instead of writing is key to good documentation. </b></div><div><br></div><div>Showing examples through code examples, screenshots, and graphics will help your technical documentation come alive, especially with clarity. Sometimes, your audience might use your examples as a shorthand way to comb through the documentation. So, make your examples count.</div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-41989443562429449202023-02-07T13:31:00.001-08:002023-02-07T13:31:57.974-08:00Salmagundi within DocumentationAccording to Meriam Webster, <a href="https://www.merriam-webster.com/dictionary/salmagundi">Salmagundi</a> is:<div><br /></div><div><i>1. A salad plate of chopped meats, anchovies, eggs, and vegetables arranged in rows for contrast and dressed with a salad dressing</i></div><div><i><br /></i></div><div><i>2. a heterogeneous mixture : POTPOURRI</i></div><div><i><br /></i></div><div>Salmagundi is also a name of various publications throughout the years. But I don't want to turn this post into a salmagundi. So, I digress.</div><div><br /></div><div>While salmagundi might be a tasty dish, it doesn't taste good in documentation. Unfortunately, salmagundis are a common problem within documentation. Salmagundis obscure, confuse, and can lose the reader. They're bad, especially when your reader needs to learn critical information. What do I mean by salmagundis in documentation?</div><div><br /></div><div>It's when documentation goes onto over-technical tangents or tries to cram too much information into one document, especially if it's irrelevant information. So much so, you end up with a technical word salad. But sadly, this is the state of much technical documentation out there. I can't count how many times I've seen this be the case. So how do we avoid creating technical documentation salmagundi? Here are some tips. They're not exhaustive but they should help.</div><div><br /></div><div style="text-align: left;"><b>Know Your Audience</b></div><div style="text-align: left;"><b><br /></b></div><div>This is the key to start your documentation. If you know your audience, you'll know how much information to include, how much to leave out, and what kind of information you need to write.</div><div><br /></div><div><div style="text-align: left;"><b>Know What You're Documenting in 1 Sentence</b></div></div><div style="text-align: left;"><b><br /></b></div><div>If you understand what you're documenting, this makes a big difference. If you can sum up what you're documenting in one sentence, you'll know where to go. For example, if I said "I'm writing about how to make coffee," then this will direct what steps or information that I need to write. </div><div><br /></div><div style="text-align: left;"><b>Focus the Documentation</b></div><div style="text-align: left;"><b><br /></b></div><div>If you focus on what you're documenting, this reduces the chances of it becoming a technical word salad. You'll know what points you want to write about. For example, if I were to create a user manual on how to run coffee maker, I'm only going to show you on how to run the coffee maker. I'll include some troubleshooting tips. I might even include the suggested amount of coffee for each scoop to put into a filter. But nothing beyond that. If we don't focus our documentation, we'll get lost in our writing. And that won't be helpful to anyone.</div><div><br /></div><div style="text-align: left;"><b>Leave Out Irrelevant Information</b></div><div style="text-align: left;"><b><br /></b></div><div>This is an extension to the previous point. But it's worth noting. When you write a document, you need to leave out the irrelevant information. You can overwrite by including every tidbit of information about something. But you risk confusing your readers, especially if the information is irrelevant. </div><div><br /></div><div>Back to the coffee maker example, I'm not going to mention how the coffee maker was made or what kind of roast would be best. Or even, how to store your coffee. All these points are irrelevant on how to use the machine. You only need to know how to run the coffee maker. Anything else confuses audience or distract from you need to know. </div><div><br /></div><div>There will never be an end to the information you can bring up. But a lot of it is neither relevant nor helpful to your reader. So if strays from the point of the document, leave it out! Once you finish writing the document, look through it again and cut what irrelevant information that remains.</div><div><br /></div><div>I love what Mark Twain once said about books. And I believe it applies to documentation. <a href="https://bookriot.com/mark-twain-quotes/">Twain said</a>:</div><div><br /></div><div><i>"<span style="color: #010101; font-family: "PT Serif", serif; font-size: 19px;">A successful book is not made of what is </span><span style="color: #010101; font-family: "PT Serif", serif; font-size: 19px;">in</span><span style="color: #010101; font-family: "PT Serif", serif; font-size: 19px;"> it, but of what is left </span><span style="color: #010101; font-family: "PT Serif", serif; font-size: 19px;">out</span><span style="color: #010101; font-family: "PT Serif", serif; font-size: 19px;"> of it."</span></i></div><div><br /></div><div><div style="text-align: left;"><b>Consider Multiple Documents</b></div></div><div style="text-align: left;"><b><br /></b></div><div>Now there are times when you need to cover a lot of information. Just listing steps to your reader might not give them the whole picture about a product or service. If you run into this situation, then consider writing multiple documents. </div><div><br /></div><div>So if someone goes through the steps to run a coffee maker but needs to know to grind coffee beans and store them, then write two other documents. One is how to grind the coffee beans. The other would be best practices to store the coffee beans. Breaking down in smaller, more focused chucks goes a long way.</div><div><br /></div><div>Especially now, when a lot of documentation is digital. You can write short documents and hyperlink them to each other. So, if a reader needs to find further information, they can go to the document that's relevant to them instead of thumbing or scrolling through one big document to find it. </div><div><br /></div><div>When I first started technical writing, we would jam as much information as we could into one document. We would sometimes break it into a couple of volumes. But we were doing this because of printing costs. But now, creating digital documents is a fraction of that cost. Sometimes, you can create digital documentation for free. So, there's no excuse to jam everything into one huge document, especially if you only write digital documents. So break up the documentation into easily, digestible information. </div><div><br /></div><div>These tips should help keep the documentation focused like a themed dish instead of a salmagundi. It won't be perfect because no documentation is. But, it should go a long way. Keep on writing.</div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com2tag:blogger.com,1999:blog-4831536563935512450.post-63537050855501939412023-01-30T15:28:00.005-08:002023-01-30T15:50:01.119-08:00We'll Hang up Our Pens Someday Recently, Pat Buchanan said <a href="https://www.newsmax.com/us/pat-buchanan-columnist-retiring/2023/01/20/id/1105287/">he was retiring his long running column</a>. This blog is beyond the scope of politics, so I'm not interested in discussing Pat's stances one way or the other. I'm interested in this angle: We writers, regardless of our stripes, will someday hung up our pens. <div><br /></div><div>We will someday write the last book, last blog, last technical documentation, the last copy, the last whatever we do. We will all someday write our last word. </div><div><br /></div><div>If you say, I'm not hanging up my pen ever, well you don't have a choice. There might come a day where you're no longer able to write or you'll draw your last breath. In any case, you'll be hanging up your pen.</div><div><br /></div><div>The reality is our writing pursuits and career have an expiration date. But we don't have to dread this impending end. If anything, it should give us more focus to write, since we only have so much time. One thing we can stop because it's an emotional waste of time is self-wallowing. You never be good as any other writer because you can't. All of us are different. <a href="http://www.williammcfadden.com/2016/02/dont-dare-to-compare.html?m=1">Comparing each other</a> doesn't go anywhere. So, don't do it! Also, if you keep talking about writing but don't write, then you need to make a decision. Is writing important to you? If so, write. If not, move on to something else. Writing isn't a glamorous pursuit. It's a hard road. To me, for now, it's worth it.</div><div><br /></div><div>Finally, when we write we need to decide why we are writing. What's our focus and why. What's your passion? For me, I like technical writing because I like to help others and I want to bring glory to God through it. I'm planning to do this until God calls me to do otherwise, He returns, or I draw my last breath. While I still can, I want create the best documentation that I know how. </div><div><br /></div><div>So, write while you still can and know why you do it. We'll all have to hung up our pens, so make it count. </div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-25158320913077864052023-01-24T14:54:00.003-08:002023-01-24T14:57:23.515-08:00Technical Writing Isn't BoringI once saw a movie where an editor insulted a writer over her manuscript for a book and said she needed to write user manuals. I was incensed when I saw that and jeered at the editor. (Maybe I'm exaggerating but I did say "excuse me?" at the character.) <div><br /></div><div>It's funny because that actually happened to me in a previous writing life as a journalist, where an editor told me that I was better off as a technical writer.<div><br /></div><div>Whether it's in movies or in real life, there seems to be a sentiment that technical writing is boring. It's sleepy. It's dull. It's lifeless. Really?! </div><div><br /></div><div>How's it boring when you get a chance to always learn something new, whether it's entirely new product or an update? How's it boring when you can get a chance to write for different industries or subjects? One of the benefits of technical writing is you can always expand your knowledge base. Boring is if your mind is stagnant.</div><div><br /></div><div>How's it boring that you get help people through your writing? You can get a sense of fulfillment knowing that you helped someone accomplish a new task. </div><div><br /></div><div>If you write documentation just right, it can be like <a href="https://www.youtube.com/channel/UCsDtTzkvGxxw95C4IOfZ7dw" target="_blank">one of those videogame walkthroughs</a>. The genius of a walkthrough is that you get to go on a journey through the videogame and the purpose is that you help someone through the game. It's the same with documentation, just without the commentary or shouting. Taking someone on a journey explaining a product or service might be draining but not boring. Boring is just remaining on Step 1. Technical writing takes steps 1,2,3, and beyond till the end.</div><div><br /></div><div>How's it boring when you can meet different Subject Matter Experts (SMEs) to help you get the technical information you need to write the documentation? Boring is when you completely rely on own imagination, thoughts, and view. Your writing can get pretty stale, pretty fast, so it becomes boring. </div><div><br /></div><div>I met SMEs from across the globe and from all walks of life. Their takes on things and their knowledge has always helped me. The documentation usually turns out better than I could imagine, even if I couldn't see it at the time I was creating a document. Why? Collaboration is what can give technical writing life. </div><div><br /></div><div>And if you write in active voice and clear and concise prose, it's anything but lifeless. Passive voice and verbose sentences are the bane of technical writing. They not only confuse and muddle but are lethargic and vapid. So we need inject the syntax with active, concise language to bring life to documentation. </div><div><br /></div><div>Clear information isn't boring. Boring is stuffy text, pontificating or rambling on to whatever it was about. And you get lost what we're reading, or in my case, you just fall asleep.</div><div><br /></div><div>Writing documentation like a flowing river won't put your reader or you to sleep like a meandering creek might. </div><div><br /></div><div>Well, maybe a white paper on some theoretical concepts might put me sleep. But for others this keeps them up all night. You can have white papers that are engaging reads.</div><div><br /></div><div>Technical writing can be hard, frustrating, draining. Boring? Don't think so.</div><div><br /></div><div><br /></div></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-20575324165217273512022-11-17T22:48:00.001-08:002022-11-17T22:48:51.423-08:00Perseverance InsteadI remember a martial artist, who is a master of his art, once told his students that he didn't get to his belt rank because he was any good. He shook his head as he spoke to them. No, rather he got to his level because he didn't give up. He encouraged his students to do the same.<div><br></div><div>I appreciate those who tell others to perservere. This is the only way to get better at anything, even with technical writing.</div><div> </div><div>I didn't get to the level of where I'm at as a technical writer because I'm any good. Far from it. I don't think I'm a good writer. I didn't get to it because I'm smart. I don't think I'm that intelligent. I only got to my level of technical writing because God kept providing opportunity after opportunity and I preserved, even when I didn't know what my next gig was. </div><div><br></div><div>Anyone can become a technical writer but not everyone remains one. Anyone can persevere when something's easy. But that's not true perseverance. It only becomes true perseverance when it's hard.</div><div><br></div><div>Technical writing can be difficult, gruelling, and thankless. It feels like you can't write anything when your documentation gets picked apart. But before you slump into despair and give up, remember these difficulties can help you grow. You can't get better as a technical writer unless you know what to improve from. That's why feedback is important. Improving your technical writing only comes through mistake after mistake. You just have to persevere. Only this road of perseverance can help you become a stronger writer. Once you get to the other side of the troubles, you'll see how they helped you grow until the next storm. Each storm is worth going through, if you want to get better.</div><div><br></div><div>But before you rush into a storm, count the cost. Is technical writing worth it? It can be demoralizing at times. But it can also be rewarding. If you feel technical writing is a worthy trade, then keep going no matter what. Otherwise, look for something else instead.</div><div><br></div><div>I find technical writing a worthy calling. I love to write and structure information. I also love to help those in need. For me, technical writer combines those two together. </div><div><br></div><div>Until God calls me to do something else, I'll keep persevering. And if you're a technical writer, who's on the ropes, don't give up either. You're not alone. I've been there and it's eventual that I'll end up on the ropes again. We all end up there. It won't be the first time nor the last time till we hang up our pens, pads, and keyboards. If you don't think you can hang on, then ask God to help you persevere. He will help you get through. He has helped and continues to do so. Don't give up.</div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-85242527106403337202022-10-11T16:02:00.001-07:002022-10-11T16:02:05.591-07:00Collaborate, Collaborate, Collaborate Someone recently asked me if a technical writer is someone who collaborates with SMEs and takes technical jargon to make it into plain, easy-to-understand language. I responded with a resounding yes. They were happy with this response because others have told them otherwise. <div><div><br></div><div>I don't understand why some are trying to change the definition of a technical writer. If I had to venture a guess, it might be they're trying to make a technical writer "a more valuable" role. But these changes tend to be (not always) counterinituitive, confusing, and overstepping. And, if you keep changing the definition, the role of technical writer ceases to be.</div><div><br></div><div>It's true we technical writers might do more than what this person asked me. I have. But at the heart of technical writing, besides writing concise, clear sentences, is collaboration, collaboration, collaboration.</div></div><div><br></div><div>Collaboration with the SMEs is the lifeblood of technical writing. Everything flows from this effort. Without it, you have no documentation. (Or at best, stilted, inaccurate, and myopic ones.) </div><div><br></div><div>This type of writing is a joint effort. Unless you're creating the tool by yourself, you don't make up text out of the thin air. Technical writing is based something else greater than the writing itself. And someone almost always has created this something else. So your job as a technical writer is to collaborate with that someone, also known as a SME, to take that technical information of this something they created to make it clear, so your audience can easily understand it. </div><div><br></div><div>As a technical writer, you not only have to continuously sharpen your writing skills but also master the art of collaboration. This skill many lack. When you can collaborate well with others, you've already added greater value to your role. How well anyone can collaborate can make or break documentation (or even an organization itself).</div><div><br></div><div>The challenge is taking other perspectives on the same information and present it in a unifying voice through documentation. But that's also the fun and rewarding part. </div><div><br></div><div>Through collaboration, you end up creating something better you can imagine. We're only limited by our own thinking. So when we work with others, it expands our mind to where we can take the documentation. And when you publish a document, it should not just give us a sense of accomplishment but also help us stay grounded and humble, since it's a team effort.</div><div><br></div><div>You have to lay aside <a href="http://www.williammcfadden.com/2019/03/technical-writing-no-room-for-egos.html?m=1">your ego</a> as a technical writer. Otherwise, you have no business being a technical writer. If anyone is telling you otherwise, especially if they come from within our circles, we need to push back and say no. </div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-72644725408515620892022-10-03T16:01:00.003-07:002022-10-03T16:02:38.918-07:00Benefits of technical writing This post is aimed at either those who are thinking about becoming a technical writer or are new at it. But if you're also a seasoned vet, feel free to come along for the ride too.<div><br /></div><div>The following shows how technical writing can help you become a stronger writer. This isn't an exhaustive list. These are just ones that came to mind. </div><div><br /></div><div><b>Improves your writing </b></div><div><br /></div><div>The first benefit of technical writing is that it can improve your writing. When you're constantly documenting, you're constantly writing. And when you're constantly writing, you're constantly getting better. </div><div><br /></div><div>Writing is like anything else. To get better, you need to practice, practice, practice. It's also real world experience to improve your writing. You'll most likely get feedback on what you wrote, so it can help you know how to better document something.</div><div><br /></div><div>Also, as a technical writer, you need to write succinctly. Be clear. Be concise. Be straight to the point. Just explain how something works. To become a stronger writer, write in short, clear sentences. Preferably 20 words or less per sentence. Also, write in <u><b><a href="https://writingexplained.org/grammar-dictionary/active-voice">active voice</a></b></u>. If you're explaining how perform a task, use active voice, so it's clear who's performing the action.</div><div><br /></div><div>Your goal as a technical writer is to clearly communicate a point to your readers. This might seem overwhelming. But don't worry. The more you write, the easier it will get to communicate clearly. Writing will be always be hard work, but you'll know what to do as you gain more experience. </div><div><br /></div><div><b>Reduces or eliminates writer's block</b></div><div><br /></div><div>The second<b> </b>benefit of technical writing is it can reduce or eliminate writer's block. What helps in is the fact you have something to write about in front of you. If you have access to a software or a tool, you don't have worry about formulating words out of thin air. You just have to explain how something works based on how it functions. You might also have to describe it, but you don't rely on your imagination. Now, if you don't have access to what you're writing about, make sure you get it.</div><div><br /></div><div>Once you get an understanding how the tool or software, the words will just flow out. There were times, even I created an outline of a document and interviewed the SME, I didn't have much to say. But after I was able to test and play with the product I'm writing about, the writer's block dissipated.</div><div><br /></div><div>This seems like an unfair advantage since I have something that's front of me to write about. But anything that gets you past writer's block counts. Let's not assume you must solely rely on your own mind to get pass the blocks. That's not only an unrealistic expectation, that's just false. Any honest writer will admit something outside of themselves helped them overcome writer's block. </div><div><br /></div><div>Technical writing just so has it built-in as a profession to overcome writer's block. This built-in remedy is seeking an understanding of what you're trying to write. And if you apply across the board, where you have a clear direction of what you're trying write, you should be overcome the blocks when they come.</div><div><br /></div><div>Before I became a technical writer, I used to be paralyzed by writer's block constantly. Even when I was a journalist, I struggled to write an article. But now, I can write past the block. Many times, I write way more than I should and I have to prune back quite a bit before I publish. </div><div><br /></div><div>Now, we'll always encounter writer's block because we're human. But having a good understanding or direction what you want to write should help you move past it. This leads us to the next benefit.</div><div><br /></div><div><b>Organizes your thoughts, even for your creative side</b></div><div><br /></div><div>Technical writing can help you organize how you write information. <br /></div><div><br /></div><div>When you're explaining how a product works, you'll explain it in a logical order. For example, if I had to explain how to use a wind-up toy car, I would say something like this:</div><div><br /></div><div>1. Remove the car out from the package.</div><div>2. Place the car on a smooth surface.</div><div>3. While on the surface, hold the car and turn the wind-up key clockwise until it's fully wound.</div><div>4. Let go of the car. </div><div><br /></div><div>Explaining things in a logical order wouldn't just apply a set of instructions in a document. You'll be able to structure the doc in a logical order. And if there are a set of related docs, you'll be able to structure them in a way it makes sense.</div><div><br /></div><div>This is not something you will be able to pick up overnight. The more you understand the product or service you're writing about, the easier it will become to organize content and documentation in a logical order. Being able to map out documentation is key to becoming a solid technical writer.</div><div><br /></div><div>This benefit isn't confined to technical writing. You can use in other forms of writing, such as novel writing. If you can map out a novel, you can increase your chances in finishing it. (Pantsing a novel is good too. That's my favored approach with first drafts. But if you struggle with writer's block, then mapping might be better.) </div><div><br /></div><div>The difference between writing and great writing is not the words themselves, but how you arrange them. </div><div><br /></div><div><b>Better see big picture and details</b></div><div><b><br /></b></div><div>This fourth benefit also doesn't come immediately; it just emerges. As you understand what you're writing about, you'll start forming a holistic approach to documentation. If there are a set of products or services, you'll start forming mental links between them and creating a documentation chain how they fit together. And as you deepen your understanding of these products and services, you can see how they can benefit your customers. And once you see this bigger picture, you'll have a better grasp on how to write the documentation. Then, the quality of the documentation improves.</div><div><br /></div><div>As for the details, it too just emerges over times. At first, you might start off just catching grammatical or stylistic issues from either Subject Matter Experts (SMEs), fellow technical writers, if there are others, or yourself. But as you go, you might start noticing other details, such as wonkiness in the User Interface (UI), the pictures or code examples don't reflect what's in the text, or the product or service doesn't do what's supposed to. </div><div><br /></div><div>Once you get more in tuned with what you're writing about, your eye for details sharpens. You're not going to be perfect, because no human or even machine is. So, toss that unrealistic expectation into the trash. But, you'll pick up on stuff that's off-kilter. By having an eyes for details where you can tell those who create the product or service if you see something, you might make a difference in improving how your organization can serve their customers.</div><div><br /></div><div><b>Focuses your writing </b></div><div><b><br /></b></div><div>I love this quote from Mark Twain about what makes a successful book:</div><div><br /></div><div><i>"A successful book is not made of what is in it, but what is left out of it."</i></div><div><i><br /></i></div><div>We can also apply this to technical writing, which leads us to the fifth benefit. Technical writing can help you focus your writing.</div><div><br /></div><div>Once you know you understand your audience, you can focus what information you want to include in your documentation. For example, if you there's a screen capture tool and it's for a typical user, you will only include step-by-step instructions on how to take a screenshot. You wouldn't any technical details or backend information about this tool. Now, let's say I had to write documentation about this same tool for backend developers, then I wouldn't include the step-by-step instructions on creating a screenshot. Instead, I would probably create an API documentation for this tool.</div><div><br /></div><div>Great writing isn't just simply the words or how you organize them. It's also what you include and what left out. It's about focus. This is why <a href="http://www.williammcfadden.com/2016/08/audience-matters.html?m=1">knowing your audience matters</a>. </div><div><br /></div><div><br /></div><div><b>Always learning something new</b></div><div><br /></div><div>This last benefit is built into technical writing. As you document a tool or service, you learn something new about it works. Even if there are no new products or services to document, you learn something new through upgrades, revisions, or updates of these existing products or services. When there's something new to learn, this can keep your writing fresh and further deepens what you know. As you deepen your understanding, your writing also deepen. </div><div><br /></div><div>I've never felt technical writing gets stale because you can become this <a href="http://www.williammcfadden.com/2019/04/always-expand-your-knowledge-base.html?m=1">ever-expanding knowledge base</a> of information.</div><div><br /></div><div>The learning never stops, you just choose to stop learning.</div><div><br /></div><div><b>Highs and lows but still good</b></div><div><br /></div><div>I can say more but I think you get the picture.</div><div><br /></div><div>Technical writing has had its highs and lows with me, even times when I want to be done with it. But it's the style of writing that I enjoy. I get to write, help others by explaining something to them, and get paid well for doing this. Sounds like a good deal for me. </div><div><br /></div><div>I've become a stronger writer from technical writing. I still enjoy it, even after all these years. I continue to get stronger as I go along. Lord willing, I'll continue with technical writing. And I hope you either jump into the technical writing world or will continue with it too.</div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-34002920021454513702022-09-14T16:03:00.000-07:002022-09-14T16:03:10.908-07:00Hard at timesThroughout my journey as a technical writer, I've encountered other technical writers who fall under a few camps. The following is not an exhaustive list. One camp is they're passionate about technology or the industry they're writing about. Another camp is they use technical writing as a springboard for career advancement. A third camp is it's just a job for them. Finally, they're ones who are passionate about writing. <div><br /></div><div>Typically, I've encountered technical writers that are in the first camp or seem to be in this one. That's great for them. But I don't fall under the first camp. It's hard at times to be passionate about technology or industries. These subjects are interesting but they get old eventually. Also, it just comes back to making money, regardless they spin it. Now, there's nothing wrong with making money. I like to make money too. And I believe in free-enterprise, if it still exist and if it's done by honest and just means. But life is <a href="https://www.biblegateway.com/passage/?search=Luke+12%3A13-21&version=NIV" target="_blank">more than just making money</a>. <div><br /></div><div>I don't care to use technical writing as a springboard. I'm content as a technical writer. So when corporate well-to-dos ask me where do you see yourself in blah, blah, blah, it's like I'm talking with someone from another planet. (Now, I wouldn't mind speaking with extraterrestrials.) Why would leave creating documentation for some middle management position? No thanks. Not a good trade for me.</div><div><br /></div><div>Technical writing isn't just a job for me either. It's a craft. But it's also not my life. God and my family are. So, this leads me to the last camp, which seems to be the smallest based on my travels. But I don't like to write for writing's sake. So, I don't completely fit this camp either. I love to write with a purpose. If there's no clear purpose, then I don't want to spend the energy to write. I don't find it a good use of my time.</div><div><br /></div><div>So, if I'm not passionate about technology or industry, "career advancement", or for writing's sake, then why I do it? I'm a technical writer for three reasons. One, I like to write. Two, I like to help others. Three, I like to find a good way to provide for a family. As far as I know, technical writing is the best way to combine these three passions together. </div><div><br /></div><div>Whether we should be inundated with technology or ruled by industries is another conversation that I may address someday in this blog. But for now, I'm just here to help guide others through the informational and technological labyrinths. My desire to write and help others is what drives me to understand these subjects, so I can write about them well. And my desire to provide for my family fuels my technical writing journey to continue, even though <a href="https://www.biblegateway.com/passage/?search=Luke+12%3A24-31&version=WEB" target="_blank">God is the One who really provides</a>. I'm just here to follow His lead on the means, even though sadly I've gotten in His way to do so many times.</div><div><br /></div><div>So when others ask me about what tools to do documentation or get into debates which one is better, I don't care. I can tell you pros and cons of tools I've used, but it's not a hill for me fight and die on. I will use whatever tools I have available to create good documents. </div><div><br /></div><div>I care more about the bigger picture: Creating clear and accurate documents for the intended audience. I'm more interested in what makes good documentation than certain toolsets. I find too many technical writers or higher ups get hung up on the latter rather than the former. What is the point of tools if documentation is confusing, wrong, or overwhelming? Let's stick to good documentation principles and rest will follow.</div><div><br /></div><div>Maybe I'm in the wrong field. Maybe technical writing is really for technophiles and corporatocrats. Maybe I'm just an anomaly, but that's thinking too highly of myself. Maybe I should look elsewhere. If there were a better place for me, then I'll go there. Maybe if I could just speak better and verbally explain how something work, I would ditch the writing thing. Writing is great but also very painful and draining. But this kind of thinking like this is fruitless and wasteful. For now, unless God makes it clear, I'll stay here in this technical writing game.</div><div><br /></div><div>God gave me a gift and I will use it to glorify Him by writing clear, accurate, and easy-to-follow information so others can understand. I spent far beyond enough years doubting whether God gave me this gift and skill, so I can hone it. I'll go with it till I can go on no more. In the meantime, I'll keep on writing in the tech world.</div><div><br /></div><div> </div></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-36598852804722988732022-08-27T23:14:00.001-07:002022-08-27T23:14:39.247-07:00Can't Write Everything and That's OkayOne of the main reasons why I chose the writing craft because the possibilities seem endless. But for a hundred ideas, I will commit one, two, or maybe three to pen. And only one of those ideas, I'll see it through and publish, while the other sits as a draft until I decide its fate. Why do this? Why not write everything? I can't. I won't. And I'm okay with that. <div><br></div><div><b>Too Much is Just That</b></div><div><br></div><div>Like we shouldn't say everything that's in your head or take a picture of every experience, unfortunately in our time, too many do so, we shouldn't write everything that comes to mind. We shouldn't. But, too many do so.<br></div><div><br></div><div>The problem in our day isn't the lack of content but the overabundance of it. A lot of stuff out there is crap or worse. So rather than getting a lot of good content, we get a lot that's empty, flaky, or downright fake. (The last point I'm referring to things that should be non-fiction but turn out to be fantasy). </div><div><br></div><div>This kind of content is like over-processed food to the mind. </div><div><br></div><div>Like those who suffer from health problems from over-processed food, our minds, emotions, and souls suffer from over-processed content.</div><div><br></div><div>How does reading another article on something trival help enrich you or someone else? Or is it just something that fills time, while you're scrolling through your phone or flipping through a magazine waiting? How about reading content that's says it's true but turns out to be based on half-truths or lies? How does that help?</div><div><br></div><div><b>It's</b> <b>About</b> <b>Prudence</b></div><div><br></div><div>When you write, I believe prudence is key. </div><div>If you're working on a project that's sunk in the muck and mire because you're neither equipped to handle or there's absolutely no direction, you could be wasting your time and energy. You're defeating the purpose as a writer by not focusing on projects you can do better with less effort. (Trudging through the slog of writing is okay, but to be stuck completely and it gets worse the more you try is not.)<br></div><div><br></div><div><b>Dose of Realism</b></div><div><br></div><div>While as a writer, you should strive to grow and expand your abilities and horizons, we also need to be realistic and humble. We need to be aware of our limitations.</div><div><br></div><div>Before we commit to writing something, we need to ourselves some questions: </div><div><br></div><div>- Do I have the ability or time to do this?</div><div><br></div><div>- Do I really know about the subject I want to write about?</div><div><br></div><div>- Is this helpful to others?</div><div><br></div><div>- Is this a good use of my time?</div><div><br></div><div>- Am I filling a need?</div><div><br></div><div><div>- Is there someone else who has already done a great job or can do a better job than me? </div><div><br></div><div>- Is this about my ego?</div></div><div><br></div><div>The world is big enough for all kinds of writers. So, why not give others their due and find the area you can write about and excel there.</div><div><br></div><div>Writing is a balancing act. If we want to be good at this craft, we need to also learn to discern whether to create something or just defer it off to others. Only you can truly answer where that line is. (But if it's solely about ego, don't write it.)</div><div><br></div><div><b>What about Technical Writing</b></div><div><br></div><div>So, what does this have to do with technical writing? Much in every way. While we should document everything, especially if the intended audience needs it, there's also over-documentation. </div><div><br></div><div>(As a technical writer, I don't determine what gets written, the organization does. I may give my thoughts on what should happen. But, I don't get a final say.)</div><div><br></div><div>Over-documentation can be confusing and overwhelming to your audience. </div><div><br></div><div>Who wants to read through reams or scroll through reams of information to get what you're looking for? I know I don't. </div><div><br></div><div>I believe in documenting every <u>crucial</u> piece of information of a product or service. But if we write about every detail or variable about a product or service, we risk getting the customer lost, where they may miss what's important to understand on how to use something.</div><div><br></div><div>For example, let's say you want someone to choose option Y after selecting option X. But then you go on and on about why this choose option Y. Then, the mindset of creating these two options. Who cares! You just tell them "Once you select option X, choose option Y." The other stuff should go in a white paper or some marketing copy. Instructing someone how to do something should be focused on taking someone through the steps till they're done.</div><div><br></div><div>In some cases, over-documentation can be condescending and you risk losing the audience you're trying to reaching. You wouldn't tell someone how to turn on a computer if you're telling how to use a certain software. The assumption is they know how to turn a machine. You're simply there to walk them through on how to use the software. If they don't know how to use a computer, then it does no good to explain a particular software.</div><div><br></div><div><b>Look At Design </b></div><div><b><br></b></div><div>If you look at what people in <a href="https://www.usability.gov/what-and-why/user-experience.html">User Experience (UX)</a> do, they strive to create something that's intuitive. The idea is where someone can pick up something and use it right away, so there would be no need to explain how through documentation. </div><div><br></div><div>But, not everyone is at the same level. And that's fine. I believe this is where technical writing can help UX.</div><div><br></div><div>If we create products and services that are friendly and easy to use and understand, then we only need to create minimal documentation. We should document where it counts. And when we do, we should create documentation that's intuitive and easy to follow.</div><div><br></div><div><b>Writing with Focus</b></div><div><br></div><div>If we focus on writing we can do and what's needed, I believe we'll have better and smarter content. Fewer but better content. We can even apply this to writing opportunities. Not all will fit your abilities, so pick the ones you can excel at and go from there.</div><div><br></div><div>I know I can't write everything or about everything. And I'm okay with that.</div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-21562156966191054022022-08-15T23:04:00.001-07:002022-08-15T23:07:28.980-07:00Yay or NayThis is very clear and well thought out documentation. Bravo! This is very confusing and lacking. It's needs to be better. <div><br></div><div>These comments that I've received from others as a technical writer. People have said positive things about my writing. Others have said negative things. And there are others who have been in between.</div><div><br></div><div>A big part of this game of technical writing is yay or nay! Thumbs up. Thumbs down. (You might get meh or sideways thumbs.) It's a brutal game at times. But that's just the way it is. But why?</div><div><br></div><div>Based on my years of doing this, it comes to this: <b>Someone's</b> <b>feelings</b> <b>about how you wrote the information is subjective. </b>The information about might be objective truth. But how you write about it and what someone thinks is not. So, no two writers are going to document a subject the same way. No two editors or Subject Matter Experts (SMEs) will react the same way to your writing. No two people within your intended audience will feel the same way either. You can't just please everyone. It's really a game of yay or nay. And the sooner you realize that, the better off you'll be.</div><div><br></div><div>But if we want to keep finding work, we can't have a totally blase attitude either. So what can we do?</div><div><br></div><div>All we can do is this: Do your best to understand the subject at hand. Do your best to understand your audience. Do your best to write the information. Beyond that, there's nothing we can do.</div><div><br></div><div>People can be fickle, contradictory, and unreliable in their opinions about what we write. It's really yay or nay. (Meh, if you want to break the monotony.) And that's just something we have to deal with. We just have to shrug and do our best. And if there are ways we can improve, even better. Beyond that, it's whatever. So knowing this, there's one thing we shouldn't do: Do <u>not </u>tie your value as a writer or as a person to what others think of you. Doing this, might make you neurotic. It's not worth it. Why tie your identity to another's whim that's flimsy than paper.</div><div><br></div><div>If you want to break the part of the technical writing game that's yay or nay, then don't tie your values to others, especially to those you work for. They are ultimate yay or nayers, sometimes in one breath.</div><div><br></div><div>If you're willing to accept this, and you don't have to agree with me, the way to break the yay or nay is tie your identity to God. He's not flimsy, like the corporate types, He's a rock, which you can firmly stand on. Unlike the corporate types, He really cares for you. He doesn't care how you write. He just simply cares and love you because He made you. For me, staying grounded in God no matter what is making all the difference. And if you accepted that, then maybe you can accept this:</div><div><br></div><div><i>Therefore, whether you eat or drink, or whatever you do, do all to the glory of God.</i> -- I Corinthians 10:31 NKJV</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-79712397802558988032022-07-22T21:25:00.000-07:002022-07-22T21:25:24.926-07:00The MomentAs a technical writer, you might have this epiphany too: <b>What you work on isn't yours. </b><div><br></div><div>Sad to say no matter how much or how long you labored away, the documentation you create isn't yours. It belongs to the company. <div><br></div><div>For some, this might not be a problem. For others, such as myself, it's harder to accept. But it's a fact that I had to accept. I may have worked on documents from their inceptions, but I don't get to own the fruits of my labor. I'm really creating someone else's product. </div><div><br></div><div>I have had to detach myself from documentation, and it's been a painful process doing so. Why? It's because I like to create and write. But what I'm writing and creating isn't mine. Even if they say you own the documentation, the obvious fact is otherwise.</div><div><br></div><div>So what do you do with this? When the higher ups want to change the direction of documentation or scrap them all together, we just have to let them. You can give your thoughts on this, if you feel there are better ways to do this. But, we ultimately have to let go. Fighting is a waste of time and energy, because it's not ours to fight for. And when the time comes when you leave or they let you go, it makes easier to leave behind the documentation. But knowing this truth shouldn't give us a pass to create subpar documents.</div><div><br></div><div>Work hard and create quality products but don't get too attached. Steward and manage these documents with excellence. But we're servants, maybe keepers, not owners of the documentation. So keep that in mind. And it's a balance we need to maintain, if we want a healthy outlook on documentation.</div><div><br></div><div>Maybe someday I'll own a technical document because it'll be tied to a product I created independently. I could imaging writing the script for a JRPG (something like Final Fantasy comes to mind) or the instructions on how to play it. But I'm not sure if creating products is my calling. Maybe an exception is publishing another <a href="https://www.amazon.com/Unlikely-Messenger-William-McFadden/dp/0578518538?ref_=d6k_applink_bb_dls&dplnkId=f5d97e5f-54bb-4c1f-a8d2-332fc7e80872">book</a> but that's yet to be determined. But who knows. Life, especially the future, can be a strange thing.</div><div><br></div><div>But, if we were honest with ourselves, we truly don't own anything. The true and rightful owner of all is God. And we should really <a href="https://www.biblegateway.com/passage/?search=1+Corinthians+10:31&version=NKJV">surround our lives and efforts </a>around God. The sooner one accepts that, the better. I have to keep learning this truth, even when it hurts.</div><div><br></div><div><i>"The earth is Yahweh’s, with its fullness; the world, and those who dwell in it." -- Psalms 24:1 WEB.</i></div><div><br></div><div><br></div><div><div><br></div><div><br></div></div></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-3749876280690924592022-05-09T22:05:00.001-07:002022-05-09T22:05:43.705-07:00Word is here to stay, at least for nowWhether we like it or hate it, <a href="https://www.microsoft.com/en-us/microsoft-365/word?rtc=1">Microsoft Word</a> is here to stay. (At least, for the foreseeable future.) After all these years, I've realized beyond doing basic stuff and slightly beyond that, I would avoid using Word when creating very intricate technical documents. But, I don't let that be the case anymore.<div><br></div><div>Long ago, when I was younger and stupidly dogmatic, I got into a heated argument at a meeting because someone suggested we use Word instead of <a href="https://www.adobe.com/products/framemaker.html">Adobe FrameMaker</a> for our manuals. Mind you, the documents were an average of hundreds or thousands pages long. I rebuffed the guy who suggested it and said in an exasperated manner Word would screw up our documents because of the sheer size and everywhere else with it. I dogmatically told Adobe FrameMaker was the tool powerful enough to handle this. </div><div><br></div><div>Oh, silly, silly me. Where is <a href="https://www.adobe.com/products/framemaker.html">FrameMaker now</a>? It still exists but it's not as widespread as it once was in technical writing circles. The claims I made about Word no longer hold water because it continues to evolve. Word can handle immense docs. I have done them in Word, cross-references and all. (My <a href="https://www.amazon.com/Unlikely-Messenger-William-McFadden-ebook/dp/B07S7MW4N4">book</a> was done in Word eventually. I first wrote it in a flavor of <a href="https://www.markdownguide.org">Markdown.</a>)</div><div><br></div><div>If you want to see how intricate Word can get, try opening the <a href="https://support.microsoft.com/en-us/topic/show-the-developer-tab-e1192344-5e56-4d45-931b-e5fd9bea2d45?ui=en-us&rs=en-us&ad=us">Developer</a> tab. I barely scratched the surface with this function, but I can see how robust this is.</div><div><br></div><div>I'm not slighting FrameMaker. I still think it's a great tool, especially with complex technical documents. I used it for many years. But who wants to use a tool that's very overwhelming at first and not very accessible to the average user. (Yes, this can include technical writers.)</div><div><br></div><div>Word allows for more collaboration with SMEs and others with comments. Word has an easier learning curve. It's those like me who overthink on how to use it. </div><div><br></div><div>And regarding sheer size of documents, I could have avocating breaking them in smaller documents. Or, if the audience didn't need to know more detailed technical information, I could avocated in removing big swaths of material to what was important to know. Looking back, I would have things differently. But it's not good perserverate over things. I did what I thought was best at the time. The important thing is learning from it and move on to make better choices.</div><div><br></div><div>I've learned to appreciate Word. Slowly but surely, I feel more at ease creating documentation in it. What's the secret?<br></div><div><br></div><div>The key is to work with the tool, not against it. We need to accept Word for what it is and not try make it something that's not.</div><div><br></div><div>I have seen technical writer conferences advocating for other more highfalutin tools. Something the average person isn't to use. Nor is it cost effective to purchase something like this. To me, it's seems like they're avoiding this simple tool. But what do I know? I'm just some schlub who types words on a screen. </div><div><br></div><div>Now, Word falls short. But so do all other tools on this planet. You just have to decide what's most accessible to use. Word happens to one of the most ubiquitous. So, make the most of it. Why fight against something that's easily available?</div><div><br></div><div>But, tools shouldn't make up your technical writing prowess. It should be skills. So, if you only had a stick to write with and the earth is your canvas to create a document, then it shouldn't be a problem. </div><div><br></div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-80872015926290899022022-04-18T19:38:00.000-07:002022-04-18T19:39:35.137-07:00Only One King and None of Us are It<b>Disclaimer: This post isn't the typical water cooler talk for technical writers. For some, such as myself, maybe it is. So if you're looking for a post related to technical writing, feel free to skip this one. Otherwise, read on.</b><div><b><br></b></div><div>There's only one King and none of us are it. In a time where we can make everything about ourselves, and you don't have to look far to see this, this truth is still radical and threatens the idea that we're the center of the universe. </div><div><br></div><div>So who is this King? This King is no other than Jesus Christ. He said so Himself to those who were with Him sometime after He rose from dead. See below.</div><div><br></div><div>"And Jesus came and spoke to them, saying, “All authority has been given to Me in heaven and on earth." -- Matthew 28:18 NKJV</div><div><br></div><div>(If He's King, then why is this world screwed up? Short answer: it's us. If you think this is all nonsense, that's your perogative. You're entitled to your beliefs and that's fine, but so am I.)</div><div><br></div><div>I'm glad He's King and I'm not. I would be a stupid king if I ruled over anything. It took me a while to see that. When I handed my life over to King Jesus, it's been freeing. I don't have to try to play this one-upmanship game with anyone anymore. Or, try to make a name for myself. And for what?! Even if I were a famous writer, it would only be a matter of time before someone else knocks me out and I'm forgotten. The prices you need to pay to get that fleeting place is futile and vacuous, especially if you trample on others or sell out to get to the top. Not worth it.</div><div><br></div><div>Instead, Jesus has given me something better. Something that lasts. And He's helping see others differently. Instead of seeing others as potential competitors, I'm seeing others made in God's image, whom I can cooperate and collaborate with. It's far more rewarding when I've worked with others on writing projects. When I've done, it's goes way better than what I can imagine. </div><div><br></div><div>Though I have a long way to go, my ambitions are fading away. I rather seek Jesus's ambitions instead (but I believe I fail at this.) I don't see the point in seeking great things for myself anymore. I once did. I had grand ideas when I first started out. I thank God those never panned out. But it's a struggle, since there's an instrinic egomaniac trap when you become a writer. But to be a good writer, it's a trap you must avoid at all costs.</div><div><br></div><div>I rather follow my King by <a href="https://www.biblegateway.com/passage/?search=John+13%253A34-35&version=NIV">loving</a> and <a href="https://www.biblegateway.com/passage/?search=Mark+10%253A42-45&version=NASB">serving others</a>. (Sadly, I wish more who claim they follow Jesus would attempt to do this. But, they'll have to <a href="https://www.biblegateway.com/passage/?search=Matthew+7%253A21-23&version=NIV">answer to God for this</a>. But, I too have a long way to go.) And, if I can do so through writing for as long as I can, then great. If not, then that's okay too. </div><div><br></div><div>Jesus is the King. I'm not it. And that's okay with me. Maybe if more relinquished their control, especially those who try to have it over others, and gave it to King Jesus, then this world wouldn't be so screwed up.</div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-89536889181566864552022-03-26T15:34:00.001-07:002022-03-26T15:36:22.171-07:00When There's a Need, Write, but What If...<div>"See a need, fill a need."<br></div><div><br></div><div>That's good advice with innovation, providing goods or services to others, and writing, especially with technical writing. </div><div><br></div><div>Whenever I've ran into different things or got into conversations with people whether it was about a user interface (UI), an API endpoint, how to maintenance or install a part, or a procedure, if there were no documentation on them and I was able to do so, I would write something to fill that need. Or, if the documentation was poor and if possible, I would try to improve it.</div><div><br></div><div>I took this advice of seeing a need and filling a need when I wrote my novel, <u><a href="https://www.goodreads.com/book/show/46160647-the-unlikely-messenger">The Unlikely Messenger</a></u>. At the time, I found no one out there who wrote something similar, especially with the challenges the main character had to face. The theological answer for my character's condition were either lacking or weren't really acceptable (at least for me). So what I did I do? I slowly over 10 years wrote a novel. Looking back, I don't know whether I should have written the novel. Maybe there was no need to do so. But what's done is done. And, I'm fine by it. In the end, I'll have answer to God about the book.</div><div><br></div><div>But what happens when there's no need to fill? Or, what happens if there's someone else already wrote similar? So they seemingly filled that need.</div><div><br></div><div>The short answer: <b>Don't write it</b>.</div><div><br></div><div>Yes. That's right. Don't write. You're wasting your time and energy. Why be just another voice saying the same thing, especially if you don't need to? You don't see, or you shouldn't see, two or more documents explaining the same thing about such and such. So, use your writing for things that don't exist yet. </div><div><br></div><div>Besides, you can always look to find needs to fill. It just may not be in the places you're looking at. So, look elsewhere. But if you can't find those needs yet, then wait. If you need to, do something else while you wait. If you also feel like you need to, freewrite or journal. But if there's really no need to write something, then don't write it. (But, if you feel like you have a unique idea, then by all means write it out.) In the meantime, what can you do is observe what's around you and listen to what others say. When you do that, you'll end up writing something eventually.</div><div><br></div><div>As for those who've written something already, if you think you can say it better, do so. Otherwise, step aside and just direct or refer others to that piece of writing or documentation if they're looking for such and such. Writing for ego's sake is empty and shallow. Been there, done that.</div><div><br></div><div>But I suppose if we only wrote what's necessary, then that would probably eliminate most content out there. Maybe this blog belongs in that pile. Hmm.</div><div><br></div><div><br></div><div><br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0tag:blogger.com,1999:blog-4831536563935512450.post-26010412271807207462021-10-28T13:34:00.000-07:002021-10-28T13:34:18.481-07:00Bittersweetness of FinishingWhenever I finish something, especially when it was a difficult journey to get it done, I get a sense of satisfaction that I finished what I started. It's even more rewarding when the purpose of what I worked on will help others. It feels good.<div><br></div><div>But I can also get a sense of sadness when it's over. If I enjoyed working with others to finish a document, I can get sad that I'll never worked with or see them again, at least not in this life. </div><div><br></div><div>Finishing something is bittersweet. But that's way it goes with all things writing. All documents, books, projects, contracts, and even jobs must come to an end. Every written work and what surrounds it must have a beginning, middle, and end. That's how it goes. I'm okay with it. I actually look forward to ending a work. But there's a sting to it, especially if you don't know if there's anything after it. </div><div><br></div><div>But, bittersweetness can go both directions. You don't have to end the sweetness of finishing with a bitter taste. It can also go this way: There may be a bitter taste at first when you end something, but there's also a sweetness, sprinkled with scariness too, on what happens next. A sweetness to writing new things, working with new people, and an opening to new opportunities and possibilities. It can be scary and unsettling but also sweet and exciting.</div><div><br></div><div>You can't taste what's sweet unless you can also taste what's bitter. So let me close with this apropos scripture:</div><div><br></div><div><a href="https://www.biblegateway.com/passage/?search=Ecclesiastes%25207%253A8&version=NIV">The end of a matter is better than its beginning</a>, -- Ecclesiastes 7:8a NIV</div><div><br></div><div> <br></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com1tag:blogger.com,1999:blog-4831536563935512450.post-27799175928779877572021-10-06T12:59:00.001-07:002021-10-06T13:01:39.849-07:00Ask Two Questions, Maybe ThreeWhen you create a document, you need to ask two, maybe three questions. But at least, you need to ask two. So what these questions? They are:<div><br></div><div><b>- What is this thing I'm writing about?</b></div><div><b>- Who is the audience I'm writing for?</b></div><div><b>- What kind of document am I writing?</b></div><div><b><br></b></div><div>Why does it seem I waffle between two or three initial questions? Well, you may not need to ask the third question because it may come up naturally in your conversations with the SME(s). Only ask the last question if you need to. Otherwise, the SME(s) may lose confidence in your ability as a technical writer.</div><div><br></div><div>But the first two questions, you should definitely ask when creating documents, especially if you're in a new setting. So why these two questions? Well, these two questions will help set the direction of your documentation. </div><div><br></div><div>If you know what you're writing about and who you're writing for, it'll help you know what kind information to write in your document. Let's say you're writing a user guide on how to use a software for storing recipes and your audience are home cooks and chefs, you're not going explain the technical inner workings of the application. You're just going to show them step-by-step how to enter and save their recipes. That's it. </div><div><br></div><div>When we approach documentation, we should take Mark Twain's advice when writing good stories. He said:</div><div><br></div><div>"<i>A successful book is not made of what is in it, but what is left out of it."</i><br></div><div><i><br></i></div><div>So, let's focus on what to write and chisel out the rest. Our audience deserves it.</div><div><br></div><div><b><br></b></div>William McFaddenhttp://www.blogger.com/profile/08693409760446999302noreply@blogger.com0