When you Doc as Code
The Placeholder
by
1M ago
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 The first and forem ..read more
Visit website
Grateful For This Blog
The Placeholder
by
2M ago
I mentioned this before, but sometimes it's worth restating. No matter how much blood, sweat, and tears we pour onto technical documentation, it's not ours. 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 an ..read more
Visit website
Not All Writers Are Equal...And That's Okay
The Placeholder
by
3M ago
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 ..read more
Visit website
Some Cliches Still Have Power
The Placeholder
by
4M ago
With 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. 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. 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. Not Just Hal ..read more
Visit website
Simple yet deep (or difficult)
The Placeholder
by
4M ago
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. 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. Simple, yet deep (or difficult) is the essence of the writing craft. It sounds like I'm contradi ..read more
Visit website
When you don't have all the pieces
The Placeholder
by
5M ago
When you create documentation, there are three fundamental questions you need to ask. 1. What is the thing you're trying to document? 2. What kind of document are you writing? 3. Who is the audience for this document? 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?  If you're in a circumstance, where you can test the product, say software or API calls, th ..read more
Visit website
QA Your Docs: Final but often rushed step
The Placeholder
by
9M ago
Once you've written the docs, it's time to release. Right? No. Other Technical Writer: But I double-checked the text and the graphics to make sure it looks good.  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?  Other Technical Writer: QA?  Me: Yes, did you QA? Other Technical Writer: What do you mean by that? Do you mean I sent the doc to QA?  Me: Well, you can do that and probably should if you have QA people. But did you QA the doc ..read more
Visit website
More Thinking, But Don't Overthink
The Placeholder
by
11M ago
What if we thought more before we said or wrote anything? I like what Warren Buffet said about how spends his time thinking. This sitting and thinking can come in handy as technical writers. 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.  Save Time and Effort Thinking more might save you time and effort on documentation. Rather than fuddling around where you might end u ..read more
Visit website
Be thorough, not Pedantic
The Placeholder
by
11M ago
As technical writers, we must be 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 pedantic.  Pedantism is annoying at best and destroys relationships at worst. It's unnecessary, short sided, and stupid. 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 q ..read more
Visit website
Show, Not Tell–Bring Documentation to Life
The Placeholder
by
1y ago
As you've pursued the writing craft, you may have heard or read the following: "When you write, show not tell." This is great advice. Showing rather than telling 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: Tell: Toby went across the rocky, cratered terrain on his rover to get to the city. 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 simples ..read more
Visit website

Follow The Placeholder on FeedSpot

Continue with Google
Continue with Apple
OR