The point is to not see dry periods as just dry periods but opportunities to explore new avenues.
Search This Blog
Friday, October 28, 2016
Putting Placeholders in your Life
The point is to not see dry periods as just dry periods but opportunities to explore new avenues.
Saturday, September 17, 2016
Don't dare to compare
Technical Writer, a misnomer
Here goes my rant about technical writing:
What is a technical writer? A writer who writes about technical things? I guess. I don't know. It seems that what considered technical writing is a complete misnomer. Why do I say this? It seems based on the many years of experience I have, I do very little original writing. At very best, it seems I can get write in the holes to make up for missing content. Most of the time, it just seems I am spending designing documents, proofreading, editing or rewriting muddied content.
Maybe I'm being picky but when I think about technical writing, it should be about writing technical content from scratch. This should be done by research, or interviewing SME, or both. But the fact that most of time, I don't get to write original content most of the time really calls into question the moniker known as "technical writer."
And if you want to write original technical content, then you need to be a programmer or an engineer. If that's the case, then these SME should write, revise, edit, design, and publish their documents themselves. Other than proofreading, rewriting the content, if needed, and designing the document, what do they need us for?
I wonder half the time, if I'm an actually a writer or a technical typist with style (now, there's a job title). But at the end of the day, it doesn't matter. I get paid to do what I do, when I do it.
I'm not being a crybaby for not writing original content most of the time. I don't mind doing what I do. I actually enjoy it. I'm merely calling in question the label "technical writer."
Maybe other terms like "content auditor" or "technical rewriter" would be better terms. I would be fine with using terms that exists already like "document designer", "technical editor," or "documentation specialists". I think these are better terms to describe to what we do, but the term technical writer, I dunno.
Maybe you're experience is different than mine. If you have written original technical content, then great. I have written ghostwritten original tech content as well. But to most, it wouldn't be considered technical writing. I'm just saying, unless you're writing original technical content, I think it's time to rethink this job label: technical writer.
Saturday, September 10, 2016
Without a shadow of a doubt
Unless you're dealing with theories or scientific findings in white papers, technical documentation must be a rock of certainty to the user. Why? It's because you're guiding your audience to do something. If you're not instructing them, then you're guiding them along to explain some information. In either case, you shouldn't fly blind on what you're writing or editing before you publish.
Friday, August 26, 2016
The third part of understanding your audience is to build a relationship with them. This is very similar to listening to your audience, except it's taking it to the next step. If you can, try to keep an open dialogue with them. See what works for them, what doesn't, and why. Have your audience complete surveys or even participate in usability tests on your documents. This can be useful to see if they can try find trouble spots as they're going through the document.
If you're able to do this, your audience will put more trust in your abilities. And you will be able to provide the audience the documentation they need. As a result, it's an ongoing, constantly-evolving relationship. It's a win-win situation.
Remember, documentation isn't about you. It's about them. A technical writer is really a servant's role. If you prefer to being in charge, then pursue project management instead. If you choose that path, then I wish you well on that journey. But writing, especially technical writing, revolves around how to best serve the audience you're writing for.
Thursday, July 28, 2016
Demystify the API
REST API doesn't mean procedures on how to create an application to help you sleep (though, I'm sure something like that out there exists).
Thursday, April 28, 2016
Healthcare and Tech Writing
But what are the factors of the increasing costs? Inefficiency and waste certainly play a role.
So what does this have to do with technical writers? Our organizational and writing prowess can at least help improve efficiency and reduce the amount of time wasted weeding through the vague and disorganized language in healthcare plans and information. If we are able to easily guide people through the healthcare world with easy-to-follow language and documentation, then we might be able to put practical steps in motion to reduce healthcare costs. There are two important things we need when it comes to healthcare documentation.
Having accurate content is fundamental to good documentation, especially healthcare. This should be self-explanatory. But for those who don't have many scruples against inaccurate information, let me explain why this important. Inaccurate health information can cause harm to others and sometimes death. This will cause members to lose trust in the health care organization, which in turn could cause it to shut down, and you would be out of a job.
Now if you're working for an organization that doesn't care about accurate information, then get away from it as fast as you can. You don't want to be associated with something that it's incompetent in caring for its customers or doesn't care about them at all.
The member or the healthcare worker is responsible for finding accurate information. But, you should play a role by supplying accurate content. Ask the right questions and make sure each you understand what the SME is saying. Have them check the content you documented. People's live are at stake.
If the information is unclear, let's says a how to instruction on operating a medical device, then these unclear instructions might cause harm or death to the one using the device. This is not something you want on your conscience. Again, make you ask the right questions and understand what the SME is saying. Do a QA check on the documentation to make sure it's clearly communicating the message it's trying to convey. You'll be surprise how many changes you might need to make sure as you go step-by-step with the product or service you're documenting. Doing the check can go a long way and will save lives in the process.
Give purpose to your career
Sunday, March 27, 2016
Tech Writing Doesn't Equal Science Fiction
Tuesday, February 16, 2016
Project Management: The Next Logical Step
If you don't know what project management is, that's okay. I was in the same boat not too long ago as well. I'll try to explain what this job is the best I can.
My question is why do some technical writers become project managers? Is this a logical progression for those of us who've been in the documentation trenches for a while? I'm not sure. But I think I have a guess as to why this seems to happen.
Now before I give my hunch on why technical writers become project managers, let me explain what project management is.
According to Wikipedia, "project management is the discipline of initiating, planning, executing, controlling, and closing the work of a team to achieve specific goals and meet specific success criteria."
In others words, you're doing everything possible to make sure a project gets properly executed. You might manage different people, such as technical writers, to make they do their part with the project.
You might coordinate with various teams to make sure they work together to move the project along.
Now what does project management have to do with technical writing?
Believe it or not, project management is built into technical writing. As a technical writer, a document is like a project. We are responsible for doing everything possible to make sure a document gets published and goes out the door with the product or service.
We come up with plans on how to complete a document. We also create an outline of what the document would look like.
Project managers have to create plans on how to complete a project. They need to have a bird's eye of the project.
Do you see a parallel here?
We have to work with different SMEs to get different pieces of content for a document, especially if it involves multiple chapters or a team of developers or engineers. You have to coordinate to make sure who does what and when. When you work with SMEs, mostly likely you'll be working with their manager to coordinate the deadlines.
Again, with a project manager, they need to coordinate with different people, teams, and managers to do their part of the project.
Collaboration and coordination are inherit in both technical writing and project management.
And finally, we technical writers have to juggle multiple documents to make sure they go out at the right time and are done well. Project managers have to juggle multiple projects to make sure they're executed correctly and on time.
I could go and go on about the similarities between the two, but I think you get the picture.
So what's my guess? It's understandable why technical writers become project managers. They want better recognition and pay for what they have been doing all this time.
Tuesday, February 2, 2016
Documentation and Gardening
I haven't suddenly shifted gears and turned this blog into a gardening one. But I think gardening and documentation have something in common: they both take tenacity and patience.
Let me draw some parallels between the two.
With technical documentation, you need to do something similar. For example, you need to find out who the audience is that you're writing for. What kind of document are you writing? What kind of questions do you need to ask the SMEs? How will you structure the document?
Answering these questions will go a long way to help you to successfully complete a technical document and create a good garden.
For example, you might need to change the location of your plants so they get more sunlight. If you have trees that have been bearing fruits for a while but the harvest declines each year, you need to prune them. There's also a possibility you need to completely uproot dead trees and plants because they're diseased or dying.
It's the same thing with documentation. Documentation isn't going to write itself. If you need to submit a technical document, you need to write it first. You may need to make adjustments to your document as it grows or evolves. For example, what you started off with may need to change because it's not reflecting the product, service, or the subject anymore. Or let's say you're documenting software and there are some new features for the upcoming release. You need to write the documentation to reflect these changes. There may even be documentation you need to trash but it's simply not applicable anymore
As a technical writer, expect you may need to do a writing and rewriting with documents you slaved away for hours, days, months, or even years. And the same thing with gardening, you may need to start over after a long time of caring for that one orchid. But if you are persistent and flexible, you should be able to overcome any obstacle that comes your way.
Wednesday, January 27, 2016
noun (plural placeholders)
Something used or included temporarily or as a substitute for something that is not known or must remain generic; that which holds, denotes or reserves a place for something to come later.
If you haven't stopped reading, let me explain why I discussing something that seems insignificant.
No job on this earth lasts forever. Job security is a myth. Work is a placeholder until something else comes along. You might need to mentally prepare yourself for this possibility.
What if they are trying remake themselves to better serve their customers? What they are being merged with another company, and the documents have to represent this change? The documents in either scenario are a part of a bigger picture that the client is trying to show to their customers.
A technical document is the result of building bridges with each other, so you can a build a bridge with the customer using the information you've written. I've seen tech writers move on to be project managers based on their experience in this aspect of technical writing.
Tuesday, January 19, 2016
Technical Writing: Ubiquitous, Instrinic, Subtle
And speaking of reading documentation, how about the things we toss to aside because they don't make any sense when we're trying to put something together. Yep, guilty as charged! The list can go on and on. I don't think you and I want to fall asleep while listing out these ideas. I'm getting drowsy thinking about it.
Whenever anyone asked me what I do and I say technical writer, sometimes I get a puzzled look. When I say I write instructions, they say okay and nod. Anyway, where the heck am I going with this.
If we are just viewing technical writing as something on a screen or on paper, we are limiting ourselves on what technical writing or, as I like to say, technical communication, is.
Technical writing is everywhere. Yes, the user guides, on-line helps, API documents, white papers, tutorials, quickstarts, how-tos, the hokey pokey and turn yourself around song, or whatever fancy, shiny titles you come up with. Other than helping to keep a writer employed, why is there so much technical writing out there?
In my humble opinion, I think it's because technical writing is intrinsic to us human beings. When we perform dance steps, fish, hunt, drive a car, using a programming language, cooking a meal, our inclination is to show others how to do this. This is one of the ways information and knowledge spreads. We have been showing others how to do something for ages.
Even things like teaching a Tae Kwon Do class, preaching a sermon, or parenting a child, are a form of technical communication. You're instructing others how to do something or you're explaining what something is. Technical writing is the written manifestation of the verbal instructions and physical demonstrations.
Finally, technical writing can be subtle. When we do our normal routines, we forget that there are steps involved and they fade into the background. We just do it. It could be anything from making coffee, tying your shoes, changing a diaper, or brushing your teeth. We don't think about it.
I remember one time I had to write step-by-step instructions on something I normally do. When I took up this exercise, I thought this was going to be easy. But when I had to write down the steps, I realized how many things I didn't think about while performing this routine task. It made me think about how much we take for granted when don't think about what we do. It's only when I began to write it down, that I paused to clear up my thoughts and to make sure I didn't miss anything.
So, the next time you look at a manual, a standard operation procedure guide, or an on-line tutorial, stop and think how much technical writing there is in our world, whether it's obvious or not.