The Placeholder
Water cooler talk for tech writers.
Search This Blog
Friday, October 25, 2024
Unless it's documentation, I don't do major revisions
Friday, October 4, 2024
Writing for Validation? No!
Friday, July 12, 2024
Technical Writing: Systematic Advantage
When my wife and I watch campy movies, there's a typical theme of a writer who has writer's block. The writers in these movies try to write something but can't. Or when they start writing on the computer, they let out a sigh, deleting everything till it's a blank screen. While these scenarios are exaggerated, there is some truth to it.
It's difficult when you must create something that relies on your mind. I know. I've written a novel before. Writer's block is always lurking around the corner. When you write, that constant inner critic is always trying to lead you to that corner. Those who are career authors, I don't envy them. God bless them for keeping their imagination going, though they struggle to craft meaningful words on the pictures they're trying to paint.
We technical writers have a systematic advantage over our creative counterparts because we document things based on what we can see and use. (I mean systematic, not systemic because while the writing process is universal, we're in a different category than creative writing. I suppose you could say we have a systemic advantage. In any case, we have an advantage.) If you're documenting user interfaces, we can walk through each step of the way to help us write. So the chances of writer's block decrease, though it can still happen.
Should we feel ashamed that we do have this over other writers? Absolutely not! But we should be thankful that we don't have those blocks. Of course, our blockers are from SMEs, developers, or whatever. We can't write anything until they're removed. But once we remove these blockers, we are to free to write till we're done. Our blockers are external not internal, so we have an advantage. So let's use it to create great documentation. Since we don't suffer writer's block like the creatives, there's no excuse for sloppy documents. Am I saying perfection? No! There's no such thing as perfect documentation. But we can strive towards excellence.
So, my hat goes off to you creatives for doing what you do. Keep writing! Thank you for building those worlds for us to enjoy and think about.
Friday, June 21, 2024
Whose Glory?
Friday, January 5, 2024
When you Doc as Code
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.
What do I think about this? Short answer is context. If you're creating or editing material in a software environment that uses Agile methodology, 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.
Save Costs
Easier to Build Bridges
More Unified Experience
https://www.writethedocs.org/guide/docs-as-code/
https://www.gitbook.com/blog/what-is-docs-as-code
https://github.com/readme/guides/code-as-documentation
Friday, December 8, 2023
Grateful For This Blog
Friday, November 24, 2023
Not All Writers Are Equal...And That's Okay
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?
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.
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.)
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!
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.
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.
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.
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.
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.
Not all of us writers are equal and that's okay.