Search This Blog

Wednesday, October 6, 2021

Ask Two Questions, Maybe Three

When 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:

- What is this thing I'm writing about?
- Who is the audience I'm writing for?
- What kind of document am I writing?

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.

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. 

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. 

When we approach documentation, we should take Mark Twain's advice when writing good stories. He said:

"A successful book is not made of what is in it, but what is left out of it."

So, let's focus on what to write and chisel out the rest. Our audience deserves it.


Wednesday, August 18, 2021

What is a Technical Writer?!

This question popped in my head after one of my kids asked me the main job of what I do. So, it reminded me of the exchange between Dracula and Richter Belmont at the beginning of Castlevania: Symphony of the Night.

Let me pick up the part of this exchange to parody Dracula:

       "What is a technical writer?!" 

       (Hear the laptop casted from my hand             and crash to the ground)

      "A herder of cats with a smattering of               writing?!"

       "But enough words! Let's document!"




Thursday, June 3, 2021

When Is It Enough?

Recently, I thought about the ending of my own novel, The Unlikely Messenger, I wrote some time ago. As I thought about it, I said to myself maybe I don't need to publish another novel.  Maybe that's enough. 

Whether I'll follow through on this, I don't know. Either way, I'm okay. But there needs to be a point when something is enough. You may disagree. You may say why not keep going? 

If you say there's no point of enoughness, then nothing will be ever be enough. And if nothing is enough, then you'll never be satisfied. And if you're never satisfied, you'll never find what you're looking for. It'll just endless striving for more like chasing a pot of gold at the end of a rainbow. Where does that lead? Where does that end?

We could go some in so many directions with this. But since this is a technical writing blog, I'll try to keep it writing related, especially technical writing.

Creating Enough Documentation

While I believe in documenting every important procedure, function, and feature, I believe there's such a thing as over-documentation. 

If we have a plethora of documents floating around saying the same thing over and over, then we may confuse, frustrate, and overwhelm our audience. Which ones should they read? Do they need to read them all?

By creating a vast sea of documents rather than a deep pool of helpful instruction and information, we may end up drowning them with information overload rather helping them dive in to find what they're looking for. So, they may forego all our documentation or go to someone else who can help them. 

You don't combat the common problem of 
under-documentation with an overreaction of over-documentation. The key is creating documents for every piece of important information.

So how do know we created enough documentation?  

Maybe one example can help. Let's say you have the same series of products but they're just different models numbers. I don't think you need to create a document for every single model. You just have one document for that product and note the differences of the model numbers, if any, within that document. 

I'm aware if we took that to the extreme, then we would have documents as big as old phone books. I'm not advocating for such an absurdity. Even with lengths of documents, there has to be a limit of enough. So where is that? If we cover the functions and how to use the product, then this should be enough. 

Writing and Rewriting Enough Iterations

When we create documents, we have to know a point when there's enough work before it goes out to the world.

We can't sit there and write, rewrite, and edit excessively. Otherwise, we'll never get anything out the door. There needs to be a point when it's enough. So when is it that? 

Here's my take. It's neither full-proof nor comprehensive but it works:

 - We covered all the needed information on how to use the product.

- You or a SME walkthrough on using the product. (If it's a service or a procedure, then have someone review it after you're done.)

- Once you finish the document, go through it again and make any fixes or edits. (A couple times through is good but beyond that is excessive.)

- Make sure document gets reviewed before it goes out. Doing a QA on a document would count as a review.

If we've done this, then all we can do is put it out. Sometimes, you just have to publish and cross your fingers or pray that it's all good. But letting anxiety or perfection paralyzing us from writing isn't an option.

While we should strive to create quality documents, we can't expect perfection. It's unrealistic.

If customers find issues with our documents, then they'll let us know. That's the beauty of feedback. It helps us improve. We just have to move in the spirit of enoughness to get things done. When we do that and let go of perfection, we give room for our customers to help us improve documents in ways we couldn't imagine.

Not Sinking into Complacency

This may sound like I'm advocating complacency. I'm not. I'm advocating for contentment. To some, this may sound same. The difference between the two is attitude. 

Contentment is knowing you have enough and you're satisfied. You have a peace in your heart that's beyond words. Complacency is you're settling or you're comfortable at a certain level because you don't want to stretch yourself and avoid hard tasks, even if an actual need arises.

Again, we can go in many directions and levels with this. But I'm focusing on documentation. So how we know the difference?

Knowing the Needs for Documentation

To know the difference between contentment and complacency, we need to look at needs. Does a product or a procedure need a document? If so, then rise to the challenge even if it's tough. If there's already a document, then check to see if you need to revise it. If you simply don't want to, then that's complacency. 

Knowing the needs and simply addressing them helps us avoid the extremes of complacency and over-documentation.

Living with Enough Writing

If we know we've done all we needed to do and said what we needed to say, then we need to be happy with what we've written.

I like what Mark Twain said:

"A successful book is not made of what is in it, but of what is left out of it.”

Twain knew when it's enough in a story. And we writers should do the same.

Unless there's a need, we need to be content with what we wrote. As long as we did our best, we can't live in regret. We have to be content with it. 

Pursuing Enough

Honestly, I haven't arrived at contentment completely, even with documentation. But I want to get there. So, I've been saying all this to myself too. But if I don't, what's the alternative? No thanks. I rather pursue what's enough, even with documentation.

I like what the Apostle Paul said to Timothy about enoughness:

Of course, there is great gain in godliness combined with contentment; for we brought nothing into the world, so that we can take nothing out of it; but if we have food and clothing, we will be content with these. -- 1 Timothy 6:6‭-‬8 NRSV

So, if I can fully arrive at godly contentment, then it'll be enough.














Thursday, May 27, 2021

Pen and Paper?

Coffee with a Side of Pen and Paper -- Photo by Pixabay


When we take notes with devices, such as computers and smartphones, it's easy to overlook a set of invaluable tools: pen and paper. When you interview SMEs about high-tech features and concepts, you may to want these trusty old school tools in your arsenal.

So why am I advocating something low-tech?

Computers Fail

Computers crash. (Yes, even smartphones crash too.) That's just life. You're in the middle of taking notes and then bam. 

Unless you have autosave, or you're saving often, all your notes are gone. But autosave will only help you if you can get your machine up and running or if you can access your stuff on a cloud. Either way, this puts an unneeded stop in taking notes. You can avoid this by simply having a notepad and pen. 

When taking notes, I recommend having at least two pens, if possible, on hand in case one dies.

Faster or At least More Natural Note Taking

Unless you're a fast and skillful typist, you can disrupt a natural flow of a conversation or interview if you rely on a machine instead of notepads and pens to take notes. If you're taking notes on a machine and you're telling a SME to slow down or repeat themselves constantly, picture the interruptions. 

Also, the clicking and clacking of keys and the device itself can be distracting. Writing notes is quiet and keeps the conversation going.

Process the Information Better

Writing notes by hand increases the chances you'll understand the information better instead of typing them in a machine. And it increases the chances of you retaining the information after you written notes.

When I've taken notes by hand, I've always felt more connected and engaged with SMEs in what they're trying to say than when I've typed notes. Whenever I jot down technical concepts by hand so I can create a document, I like feel I can better understand and remember what they're saying. 

One of my favorite things to do as a technical writer is physically taking notes. I enjoy putting pen to paper when I interview a SME, walk through a product myself, or both. (I've also done this well in a remote environment.)

Unleashes Creativity

Handwriting notes seems to increase creativity, which is a boon for writers especially ones with a creative bent. 

According to Little Things, one of the benefits of writing things out by hand is it unleashes your creativity. On the surface, creativity and technical writing seem like oil and water. But not so. When you create a technical document, especially one from scratch and no template you need creative power. 

When I've taken notes by hand, I can get inklings on how to create the document and how to arrange the information in it. 

Is Typing Notes Useless?

If taking notes by hand is superior to taking notes by devices, then why do some people continue to use them instead of going back to pen and paper? 

There are a good few reasons to not to handwrite notes. 

One, if you have a disability. If you struggle with taking notes or unable to by hand, then by all means type, use a recorder, or any other method to record notes. Don't let anyone tell you otherwise. Use what works for you.

Two, supposedly you can write more notes by typing than by jotting them down. 

Three, you can share your notes a lot easier than trying to decipher someone's handwriting. And if you're going to share, it's easier to clean up your own typed notes easier. Why bother trying to fix up your chicken scratch when you can type it.

In cases where you need to share notes, I'll concede that typing is better. Here's what one writer says in defense of typing.

Though these writers seem to tilt towards handwriting, they highlight some possible advantages to typing notes too:

https://effectiviology.com/handwriting-vs-typing-how-to-take-notes/

https://www.clearvuehealth.com/writingtyping/

But their conclusion seems to be handwriting notes is the better way to go.

What About Recorders?

Using a recorder changes the dynamics of note taking. With a recorder, I'll also concede there's a definite advantage over pen and paper. But let's not forget one thing or should I say two: What happens if the device fails or if the battery dies. When that happens and you have no back up, then that's no good. 

If you're going to use a recorder, then I recommend having a notepad and pen and actively notes while you're interviewing a SME. That way, you have two ways of capturing the information. In this case, it's like two heads is better than one. And if you're doing that, you're still using pen and paper.

What About Digital Note Taking?

One plus about technology is it can eliminate some arguments or find a radical middle ground. This may be so with digital note taking.

Digital note taking seems like a good middle ground between clicking on keys or scribbling on a notepad. It seems it's the best of both worlds. So it's tempting for me to concede here too. But my response is this: What happens if the device fails when you take notes?

Commit to Keep and Bear Pen and Paper

Aside from seemingly, possible advantages of using devices, I remain committed to upholding the right to keep and bear pen and paper. For as long as I'm a technical writer, I'll use them when I interview SMEs.

I don't care what the sirens of technology and convenience say. I'm not turning them in. Neither should you. My pens and pads will stay with me. So listen here machines! You'll have to pry my pen and notepad out of my cold, dead hands. What about you?




Monday, May 10, 2021

Kanban..Ban...Kan..Ban..Kan...Kanban

Kanban is not another way of doing the Can-Can. But doing the Kanban will get you moving.

Kanban is a method, which originated in Japan with Toyota after World War 2, of moving projects along. (But the term "Kanban", which means signboard, has existed since Edo Japan.) With a Kanban board, you can easily see a project's status. It also helps control the workflow and priorities, so you don't get overloaded. 

I've used a Kanban system before when creating documents for software releases. I felt it helped me know the progress of a release. So, I'd know whether I need to create a document or just wait until the development team moved on a project.

Kanban and Agile

Kanban boards complement an Agile environment. I've used a Kanban board in an Agile environment and I felt it made goals easy to accomplish in a software sprint. I also felt it augmented the experience where I can picture what needs to happen in a sprint.

To check out how Kanban boards could work within an Agile environment, look at what Guru99 says in Kanban vs. Agile

Electronic Kanban Boards

You could create a Kanban by just pinning to notes or cards to a bulletin board and moving them along on it. But many use electronic Kanban boards. Electronic boards help especially as companies and teams continue to go more remote. 

To get an idea how these electronic boards work, here are a couple of Kanban tools below.

Trello

My foray into Kanban systems was Trello. What I liked about Trello is you can easily create a card and drag it to the next step of the flow. I also liked you can easily add stuff to the card as things come up, even the card was created by someone else. Finally, there's Taco, Trello's husky pup. Cute little guy! I always liked whenever he'd show up during my time using Trello.

To check out Trello, here's a tour

Asana

Asana is another Kanban tool out there. I have never used Asana. But if I did, I wouldn't have any trouble with it. If I end up using Asana someday, I would feel at home because my time with Trello. 

If you want to see how Asana Kanban boards work, check this out.

Trello vs Asana

Not sure which one to go with? The Write Life compares the two.

Before You Decide on a Kanban Tool

Trello and Asana are just two of Kanban tools out there. Here's a list of other ones there. 

Before you decide which tool to use, first get a good understanding of a Kanban board. Once you do so, you can then pick the one the best suits your needs. For primers on Kanban boards, check out these out:





So if you do the Kanban, Kanban, Kanban, Kanban, Kanban, Kanban, Kanban, then your documents will move, move, move, move, move, move, move, move.

Friday, April 30, 2021

Should You Learn Programming Languages

When I see technical writing jobs requiring us to know programming languages, I ask myself this: Do we really need to know them? Do we need to learn how to code? That depends. Do you want to become a programmer who happens to write? Or, do you want to be a writer who happens to be familiar with the code you document? How far down the rabbit hole do you want to go?

As technical writers, I believe our primary focus should be on writing well. This focus takes a lifetime to accomplish. And since it takes a lifetime, our aim should be on honing our craft. The technical stuff, such as programming languages, should be secondary. (The second skill we should actually focus on is knowing our audience.) How can a document be helpful to anyone if the language in it is poor and confusing? If we're more dedicated to technical and programming skills than good writing, we defeat technical writing's purpose. While we're writing about technical and complex topics, the way we explain them is by writing in simple, clear, crisp prose. In other words, KISS. That's the purpose of technical writing.

But if you insist on learning programming languages, more power to you. If you want to add them to your tool belt, go for it. But know a couple of things. 

One, what's your end goal? Once you know this, you'll know far down the rabbit hole you want to go.

Two, it will never be enough. What programming languages are popular now will become obscure either as newer programming languages appear or become in vogue by the whims of industry and organizations. But if you're willing to be a constant student of all things tech, then by all means do so!  

I recognize just about all our tools of the trade come and go on based on outside whims. But despite those whims, we should be firmly committed in writing well for our audience. Does this mean we should stay stagnant in our technical knowledge and abilities? Far from it! It's just a matter of focus.

While I like expanding my knowledge of Markup languages, such as HTML or Markdown, I'm more focus on honing my writing skills. I only have so much time, so I rather spend it on getting better as a writer than chasing techno-phantoms.

So what about those technical writing jobs that require us to know programming languages? Why do we see a heavy emphasis to know them in the job description? In my humble opinion, I believe there's confusion on what it means to be a technical writer. All you need to be a good technical writer is the ability to take complex topics and break them down into simple and understandable language. KISS!

With these jobs, we have to decide whether to ignore them or not. If we ignore these jobs, then maybe organizations will drop these silly requirements and just ask for good writers. But if we heed them, then we must ask ourselves again how far down the rabbit hole do we want to go?

Companies that require you to know programming languages and technical and software skills are built on shifting sands, but the principles of good writing are built on a more firm foundation. I don't see the KISS principle going away anytime soon. So, I'm more focus on things that tend to last.

Should you learn programming languages? Well, how far down the rabbit hole do you want go?

Monday, April 19, 2021

Microcontent--Make Your Point Quick

"Brevity is the soul of wit." -- William Shakespeare

This proverb rings true for good writing, especially microcontent.  

Microcontent is using few words to present valuable information to your audience. Anything from a tagline to a tooltip is microcontent. Microcontent is supposed to catch a reader when they're skimming. It works! I get caught when I see keywords that catch my eye. And if you're honest, it catches yours too.

In our time, microcontent is what draws your readers in. Short. Sweet. Effective. That's microcontent. To find out more, check out here and here.