Putting Placeholders in your Life

There are times when you need to put a placeholder or two in your career. What I mean by that is when you're experiencing dry periods, it's time to take a job or two that may not be technical writing. Now I'm talking to those who are freelancers, independent contractors, or in between jobs. 

If you don't fall under these categories, that's okay. Feel free to follow along or just skip this post. If you do fall under these categories, it's a choice that you may need to make. It doesn't mean your career is over. It just means it's a stop-gap from going hungry.  Now here are some things that might help.

Don't be too proud

First off, don't be too proud to take any job. If months have gone by and you're not getting a bite, it's time you need to take a job to have food and shelter. If you think you're above it all, you won't get a job with that attitude. Be confident in your abilities but don't be arrogant. Attitude is a key factor in getting a job. 

Interviews may be determined on the tone of your voice and how you present yourself. Who wants to hire a pompous jerk? Sorry for being strong here. But seriously, who wants that except for other pompous jerks. However, I think pompous jerks can't even stand each other, so no luck there. 

If you think you're too good for a lowly service job, then you should stop reading and write me off as a hack. I can tell you this: arrogance doesn't help a writer grow. Having a humble and teachable heart does. 

But if you have a humble yet professional mindset, it will go a long way in landing a job.

 

Find a job that can use your abilities

If you need to find a job, then it would make life easier and more enjoyable if you find a job that uses some of your abilities. Brainstorm and come up with a list of jobs you would like to apply to. I'll give you a couple of examples.

Content writing is something you can easily take on since it's writing. If it wouldn't be hard leap to take, especially if you're writing technical content. The only problem with content writing, based on my experience, is that a lot of it is low pay, because there's a lot of content mills out there. 

I don't take a hard stand against content mills, because I write for them on occasion. A little money is better than no money. The issue I have with content mills is the amount of time you need to spend belting out an article or short for low pay. If you can find higher paying content writing gigs, go for it. If you do decide to go with content mills, than trying finding articles that won't take much effort or time to do. Remember your time and efforts are more important than money.

Another example is merchandising. Merchandising is similar to technical writing. They both are aiming to target a customer or an audience. They both have a process in organizing materials to create something orderly and easy-to-use. Merchandising uses an planogram to organize products or build a Point of Purchase (POP). Technical writing typically uses an outline to create documents. They both are detailed-orientated. They are both aim to foster relationships with the customers. They both use writing in some capacity. The big difference is that merchandising uses writing to create notes for internal use. Technical writing uses writing to create documents for external and internal use. 

The point is to search for a job were your skills are transferable. Not to mention, brainstorming of ideas helps you as a writer.

Don't take it personally, just be grateful

If you haven't gotten a technical writing gig in a while, don't take it personal. It's hard not to because it feels like nobody wants to hire you.  But there are other factors that we can't see like maybe companies are having budget problems or maybe they are unrealistically picky.

If you have a placeholder of a job, then don't think it's all you can get. This is just a season in your life. Just be grateful what you have. It's better than having nothing at all.

Work on honing your craft

Write. Write. Write. Writing anything during this time. This could anything from working on your cover letter or resume to starting a blog or a newsletter. Write a diary or a book if you want to.  In any case, your efforts aren't in vain. Your efforts are building up your craft, especially in the area of engaging your audience. The more you write, the more you hone your abilities as a writer.

New opportunities

Finally, take this dry period as a way to explore new opportunities. Maybe you can unlock your inner blogger or novelists during while you're working at the placeholder of a job. Or if you enjoy the placeholder job, then find writing positions in that field.

The point is to not see dry periods as just dry periods but opportunities to explore new avenues. 

Don't dare to compare

Whatever you do, don't compare to yourself to others as a technical writers. It doesn't matter whether you're trying to see if you're better or if you believe that you don't measure up to others, just don't do it. It will imprison you mentally and might affect your writing. Not to mention this is a waste of your time and energy.

There was a point in my career where I felt like a phony or a horrible technical writer because I don't have a BA. Due to some circumstances in my life, I couldn't go further in my higher education. So I settled for an AA, which I got after I became a technical writer.

When I saw other technical writers with a BA or MA, I felt very inadequate. This would get reinforced when I tried for other technical writing jobs but couldn't get them. It got worse when I saw other writers and focused on how they could write far better than me. And to top of it off, I would have some engineers who challenge me on grammar and style. I felt hopeless.

I would go to my office with my head down and would crouch in fear of engineers and others. My voice got shaky and uncertain. I was a mess for a while all because of these supposed points against me. Many times, I considered giving up not just technical writing, but writing all together.

Things were bleak until this Scripture verse came to my mind.

We do not dare to classify or compare ourselves with some who commend themselves. When they measure themselves by themselves and compare themselves with themselves, they are not wise. -- 2 Corinthians 10:12 NIV

As I kept thinking about this passage, I realized what I was by comparing to others was stupid and a waste of my time and energy. I realized I was my worst enemy. Other writers may write better than me. But so what? That's fine. Good for them. I'm not them and they are not me. And why was I assuming they are better? It could be their writing is just different. And that's good. It would be a very boring world if we all wrote the same way.

Writing is a thought process and we all think differently. The truth from this piece of Scripture started to break some light through the dark cloud over me. But the cloud was still there.

The next thing that made this dark cloud thin out was a book called Grammar Snobs Are Great Big Meanies by June Casagrande. This book was freeing for me. It showed that grammar and style are not always clear cut. Thanks June for writing such a much-needed book for us writers!

So whenever an engineer tried to challenge my editorial decisions, I wasn't threatened anymore. I would thank them for their feedback. I would change things if they were right or just simply better. If they were plain wrong or unnecessarily dogmatic, I would show them gently why I chose a certain way of saying things.

I may be a writer and know some principles of good grammar and style, but I don't know everything about it. I've even been wrong on things. Guess what? That's okay with me. As a writer, especially a technical writer, you have to be willing to learn and be humble about things.

The dark cloud was thin but still there. The last stronghold of my inferiority complex was my lack of a higher degree. It didn't lose its grip until others helped me see that my premise was faulty and nonsensical.

The dark cloud over me dissipated. I was free to pursue this simple adage: If you want to be a writer, then write.

A degree doesn't make a writer. It's what they write that makes them a writer. You can't trade experience for a piece of paper that says you're well-educated. In my humble opinion, real-world experience is more valuable than a degree.

Now for those of you who have BAs and MAs, God bless you. No one can take away the hard work and perseverance you put into getting that degree.

I have no regrets except one: the amount of days, weeks, months, and years I spent beating myself.

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.

Without a shadow of a doubt

If you put out technical documentation you're unsure of, then there's a big problem. Chances are if you're not certain of some content in a document, then your audience may be uncertain too.

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.

So how can you make sure you understand what you're writing?

Big picture

Understanding the big picture of a product or service of what you're about to document is extremely important. If you don't have an idea of what you're writing about, it will show. 

If you sit down with an SME, have them tell you briefly what something is. Once you get a gist of what you're writing, the rest is just taking the next steps. Don't get hung up on details. Those will follow as you move along. It's more important to take a step back to see the bigger picture, so you know how to create a document. 

Understand your audience

It's important to understand so you would know who are you are writing for. What kind of information will you include? What information not include? For example, if you're writing for a software company that helps electrical engineers create schematics of an electric circuit, you should find out what schematics and electrical circuits are before you proceed. However, you wouldn't explain what these things are to an electric engineer since they should know. You simply explain to them how to use the software. 

For more about knowing your audience, please check out what I said previously.

Ask Questions

If you're unclear on what you do, please ask questions. Ask and never assume. No one should expect a technical writer to be an SME. Do as much as research you can on your end. Then, ask the SME questions about the product or service you're uncertain about. Any SME worth their salt will be able to answer your questions. Don't be afraid to ask. It's better to ask plenty of questions and put out an accurate and clear document, than to put out a document that's unclear, inaccurate, and full of uncertainties.

Audience Matters

In the Lion King, Musafa's ghost told his son Simba to remember who he was. There's something that we tech writers, or we writers in general, can take that from that.  We need to remember who we are and why we are doing what we are doing.

Whether we want to admit it or not, as writers, we are doing what we do for the audience. Even if we are writing in our dairies (and yes, there are people who still write dairies, even blogs are diaries in of themselves, except they are in cyberspace), you are still writing for an audience.

Whether you are writing for one or one million, the end goal of writing is to communicate a message to the audience. With that in mind, we must tailor that message to them.

Understand Your Audience

This is key in writing a document. I can't stress how important it is to know your audience. This should be the first step before you type a character on the screen.

So why is this important? The obvious answer is for every document there is an audience. Why write anything to anyone if you don't understand who they are?

For example, you're not going to write a whitepaper for an electrical engineer audience to educate them on circuits, currents, transistors, or diodes. Since they know about electronics, you wouldn't waste your time--or theirs--defining these components. You should focus your attention on how to have electrical currents run through circuits better and with less power. Or maybe, you would show them how to create certain schematics for a chip.

Another example would be if you're creating a user guide on how to run an air conditioner written to the general audience, you're not going explain the nuts, bolts, materials, and components that were used to create the air conditioner. You're just going explain how to use it. You may also have surface technical specifications in the guide, like the amount of BTUs the air conditioner uses, but nothing beyond that. 

So before you write a document, know who you're writing for. Otherwise, the information in the document is worthless.

If you don't know who the audience is, then ask an SME or do some research yourself. Any SME worth their salt should be able to help you with this.

In any case, it's important to gauge your audience, so you know how much or how little information you need to communicate, as well as the type of information.

Listen to Your Audience

The second part of understanding your audience is to listen to them. If your audience is confused by certain portions of the document, there are missing steps, or the information is not as accurate as it should be, you need to take the feedback and improve it. In some ways, documentation is like software; it's fluid and it has bugs. Documentation gets better, like software (or at least should), if you listen to the complaints as well as the complements. Otherwise, the documentation is useless to the audience and they will find someone else who can meet their needs. So listen up!
 

Build a relationship with Your Audience

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.


Servant's role

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.

Demystify the API

What is an API? A string of random letters floating in an alphabet soup?

API is more than an obscure acronym in the ocean of technical terms. It's actually becoming very relevant in some quadrants of technical writing.

API stands for Application Programming Interface. It means basically means a set of steps, routines, and procedures to create software or applications. 

Where technical writing comes into the play with APIs is that documenting how to use the programming language to create or modify a software or an application. You may have heard the terms "API Guide" or "API Manual." If not, that's okay. I've only heard the term a couple of years ago. 

From what I gather, these types of documentation are basically user manuals for software or app developers so they can create their programs. 

There are also some terms we should know when it comes to API documentation.  I don't want to say that these cover all there is to API, but you may run into these terms when you're either looking for your next gig or when your company decides to create API documentation. They are REST, SOAP, and Endpoints.

REST (REpresentational State Transfer) 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).

REST API (or REST-ful API) means it's an API that based on the nuts and bolts and the structure (software architecture) of the Internet. This is not based on some markup language, like HTML or JavaScript, or some standard. It more of a style of an API. I'm not even sure if this is completely accurate to say. There's a reason why: REST-ful APIs depend on the organization that creates them.

Some REST-ful API can be done in JSON (JavaScript Object Notation), XML, or even HTTP. Again, it's a style or architecture an API is presented in. (API writers feel free to give some comments)

Now another type of API that's easier to pin down is SOAP API.

SOAP (Simple Object Access Protocol) API

SOAP API is more clean cut to define than REST API. No, it's not a way to create applications to produce bars of soap (again, there might an app out there to do that).

SOAP APIs are set of steps to create applications based on an XML Infoset. I guess it's good to know XML other than working with it in a structured authoring environment.

Endpoints

Another thing to note about API documentation is something called Endpoints. I have only heard of this term in the past a couple of months when I did an API document for a healthcare company.

An API endpoint is basically a procedure or a method of how an API will run.

You would typically see this with an example of code in the document. Then before or after the example, you would have the name of the method, say a command or a parameter, and the definition of it.

API endpoints depend on the organization that determines them.

Final Thoughts

It seems, at this point, the line between software developer and technical writer are blurred. Based on what I have seen, it seems that companies who are looking for API technical writers are basically looking for developers that can write. Many times that they looking for candidates who have experience with programming languages.

My question to them is, why look for technical writers if you can just use programmers to do the documentation? The only thing I can think of is that API documentation is fairly recent and somewhat uncharted for us technical writers. Whether API docs will be something for technical writers to do, or will finally just reside in the realm of software developers remains to be seen.

In any case, if you want to try your hand at API documentation, don't be disheartened. You can pick up programming languages either by being self-taught or taking courses.

Healthcare and Tech Writing

The pen is not only mighter than the sword, it's also much more helpful.

This applies to a datasheet or user manual on medical device, website content for a hospital or medical center, patient information website, or a white paper of insurance policies.  Having clear and accurate information can be the difference between life and death in some situations. So this is an area where good technical writing skills become critical, because people's lives depend on it.

Regardless of how one views the Affordable Healthcare Act (Obamacare), it has opened the doors of healthcare to technical writers. According to the Bureau of Labor Statistics, the increasing complexity of medical and scientific information will continue to create more opportunities for technical writers.

Even from just personal observation, I noticed more healthcare-related gigs or jobs for technical and medical writers. Just do an internet search and you'll see. As a technical writer, you just not only have just plethora of opportunities, but you might be able to have a chance to play a part in improving healthcare.

One of the fundamental problems with healthcare as it's currently implemented is it doesn't seem address the issue of cost. 

According to a CBS article written earlier this year, healthcare costs will continue to rise in 2016. However, it may not be all doom and gloom. A recent PWC study shows virtual care, new health advisers, and the eventual "Cadillac tax" might lower costs. Whether any of these factors mentioned here increase or decrease costs remains to be seen.

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.

Importance of accurate content

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.

Importance of clear content

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

You need to have passion for people's health and well being. Otherwise, the quality of documentation in healthcare will suffer. If you want to give meaning to what you're doing as a technical writer, then writing in the healthcare field is a place to fulfill that meaning. People's lives depend on it.

Tech Writing Doesn't Equal Science Fiction

For the love of all things decent and true, in whatever you do, don't write fiction in a technical document. In other words, document only what exists.

Some might want you to create something that's called vaporware in documentation. Vaporware is touting a feature or features in a software, or even software, that doesn't yet exist. There's also a chance it may never exist.

If an SME or even management tells you to write or document that doesn't yet exist, please gently, but firmly tell them no. Just plainly tell them, "until we have an actual feature, product, or whatever that is actually in existence, let's leave this out of the technical documents, especially user manuals." I have run across a few SMEs who wanted to document steps or entire sections in user manuals that still in dreamland.

I am picking on rare cases where people will try to cajole you to write vaporware. Most SMEs have better sense than that. But if the rarities do try to pressure you to write science fiction, then you respond with some reasons why.

Credibility Gap

Losing credibility should be reason number one in avoiding vaporware to show up in your documentation.

If you put out some documentation that should be considered creative writing, the customer will lose faith in your product(s) and even lose faith in the company itself.

If a customer is trying to use a certain feature in a software and it's not there, imagine the frustration and confusion they might have. And then their frustration and confusion becomes skepticism of your company when they realize nothing that's written exists.

Not to mention, this is cheating the customer. They paid for a software or product. It's implied that all features are present. (Now whether it works properly is different story all together.) If there are features in a document, they had better be there.

If you're having a hard time understanding this, switch the roles around. Imagine you're the customer. And you bought furniture to put together. Then, you find out half of the parts listed in the manual were never made. Imagine how you will feel.

Customers will speak out

Before I was a technical writer, I worked in food service. I was told by the store manager, while training to be a manager myself, that if a customer has a bad experience, they will tell ten others, on average, about their experience.

Now this was before the Internet became available to the public and way before social media. Imagine how far news of bad customer experience can spread. Things go viral all the time. Let's hope a company you're working for doesn't go viral negatively because they were too lazy or dishonest to actually to create the features or even the product itself.

Now if a company has a total disregard to what I've said, then in my humble opinion, they shouldn't exist--like vaporware. Instead, they should evaporate like all other bad businesses do.

Easy to forget vaporware is there

You might hear a defense of documenting vaporware that's goes along these lines: just put this in anyway because we'll go back and create the features. With all the other things you have to keep track of during a product release, it's to easy to forget vaporware is in your document.

In my early days as a technical writer, I've had SMEs tell me to put vaporware in. So I put them in and guess what happened: the document went out with the product because we never got back to it before release time.

It wasn't until I put my foot down to document only what exists that the practice of documenting vaporware evaporated at a place I once worked at.

An exception to document the not yet

There might be exceptions to documents that don't exist like a proposal internally between departments, programmers, or engineers, so that they can get an idea of what to create. But for ALL external documents that are going out to customers, it should be big NO.

Serious considerations

If you work at a company where vaporware appears in your documents, I would everything possible to stamp it out and reject any spurious material that comes your way.

If your company's management or leadership is okay with vaporware, encourages it, or even demands it, then I would quit as soon as possible. If you're a contractor, then I would stop doing business with them as soon as possible.

If the company doesn't care about its reputation, then you should, at least, care about yours.

Now if you're okay with documenting vaporware, then my suggestion is to seriously consider writing science fiction. At least with that type of writing, you will have more credibility.

Project Management: The Next Logical Step

I don't know about you, but I've heard the job title known as "project manager" thrown around quite a bit. I also met a few project managers who were technical writers at one point.

What's interesting is that I've seen career maps for technical writers and one path is project management.

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.

If there are trouble spots or impediments with the project, you might need to make some adjustments anywhere from shifting people around to coming up with a new plan on how to execute a project. As a project manager, you're there to see the project through.

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.

Documentation and Gardening

Whenever I get a chance, I enjoy giving my green thumb a workout and caring for plants that bear fruit. Unfortunately, I'm not doing any gardening right now because of a drought and other factors. However, I'm still nursing an orchid plant. Where am I going with this?

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.

Plan ahead. Before you plant a garden, you need to do some research. For example, what kind of soil are you going to use. Does the plant need more sunlight or more shade? How often do you need to water the plant?

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. 

Be persistent and flexible. To make sure your garden thrives, you need to be active in caring for your plants. Constant care will help your garden grow. You also need to be willing to make some shifts when your garden isn't flourishing.

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.

Factor in the unexpected. A disease might kill your plants. This actually happened to my zucchini plants one year. Or you might have seeds that are D.O.A. It's the same with documents. The "powers that be" might pull the plug on a project and the documents will die with it. Or the project goes in a completely different direction and the documentation needs to do the same. What if a company folds or someone you're working with suddenly quits? These are things that can happen and you need to account for these possibilities mentally when writing documentation. 

Be patient. Your garden isn't going to grow and yield fruit overnight. You shouldn't expect documentation to be completed overnight either. Sometimes, you'll be waiting for SMEs to get around to your questions when you want to finish up a section of the document. You might be waiting anywhere from hours to months to finish this up. Even if you try to follow up with the SME, he or she might not simply have the time. You need to move on with another document until they're ready.

If you are willing to deal with the dynamics of this universe, then you should be able to write technical documentation and plant a garden.

{

Why Placeholders

Today, we're going to talk about placeholders. According to the Wiktionary, a placeholder means:

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.

While they seem unimportant, placeholders help capture the big picture of a document. They are especially helpful when you have a document with fields or you are crafting a template. Rather trying to reinvent the wheel, you can simply fill in or replace the content you want. But you will have the look and feel and structure of the document you're writing.

Placeholders are also a prelude to something better, meaningful, or complete. In my humble opinion, they are a significant step to help you paint, or in this case write, an instructional or informative picture.

Now, I want to get to the heart of what I'm saying. Placeholders aren't just some bits of text or pixels on a screen. They are stepping stones in life. 

Every job we have is a placeholder. It doesn't matter whether we work somewhere for 30 days or 30 years, it's temporary. Even if you plan to work there for the rest of life, there are some things you can't control:  a company folding, a company eliminating the tech pubs team, you becoming debilitated in some way so you can't work anymore, you taking care of a loved one long-term, or even you dying.

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.

And for us independent contractors,our projects are just a placeholder until we fulfill the bigger picture. Let's say you're hired to do a project that just rebranding and minor updates on some company's documents for a couple of months. It may seem like droning busywork to us. But to the company, there's a bigger picture.

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.

And finally, our work could be foreshadowing of something better or meaningful. Some of us technical writers may go on to be novelists. Having the discipline to finish a manual can also translate into a focus on writing and completing a novel.

Or maybe some will go on to be a role where we have to mediate between people who are in conflict. As a technical writer, you have to learn to how to build relationships with different groups of people to create a technical document. Technical writing is a very collaborative process. Whether that's interviewing an SME or guiding SME through their document on how to reshape it, you're working together.

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.

Or maybe, some of us who are content with the possibility of staying as technical writers, like myself. Changing careers doesn't always mean it's a sign of something better. Just staying in the same role has its rewards. You can increase in your knowledge about subject you're writing about. Or perhaps, if you work on something from a different field, your knowledge base expands. 

I once told someone I was perfectly fine staying a technical writer. It doesn't mean I'm happy being stagnant. I'm just happy and grateful in what I do. And along the way, I've learned some things. I feel like I'm always learning when I work on a document.

So the next time you see a placeholder, ponder on what its role is and how it can apply to your life.

Technical Writing: Ubiquitous, Instrinic, Subtle

When we think of technical writing, we might come up with some different ideas. We might think of a neurotic wordsmith, straining over grammar, style, and finicky about formats when creating documentation. Or, maybe an engineer just waiting to unleash their inner writer, waiting to plaster their prose on the screen, and waiting to release to the world the greatest manual ever written. Most likely, though, they are someone who got stuck writing something because no one else wanted to do it.

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.

Hello World!

My name is William McFadden and I have been a technical writer for over 18 years. What I'm hoping to accomplish here is to share my experiences, insights, and my philosophy of technical communication. And maybe, do some actual technical writing here. I don't want to get hung up on what tools to use or whether you should learn some programming language or not. Granted, these are helpful. I'm focused on talking about some core principles of technical writing, as well as issues that may surround it. I don't speak for all technical writers out there. I'm just one guy who's been doing this for a while. I'm hoping to encourage those who are new writers to consider this writing style or prose. I'm also hoping to encourage those who have been doing this for a while to continue. Thank you for stopping by. Hope you come again soon.