No Hesitations or Regrets...Well

Write without hesitations or regrets, even if the writing sucked. Well...I wouldn't take this statement to the extreme. There are times when we should be prudent about what we write and reflect on it before moving forward to the next project. But don't slam on the brakes in hesitation and constantly look back in regret either. Have a balance. 

Writing is never about perfection. Writing is about using a creative process to make progress. When you write, it's a constant learning experience. The more you write, the better you get. So there's no need to live in hesitation or regret. If someone hates your stuff, even if it's valid, all you can do is nod, shrug, and say I did the best I could at the time.  I've found this to be true with technical documentation, especially in the software/API realm, where constant changes are the norm, even after publishing. I had people who quite frankly didn't like how I wrote something. Okay. Whatever. Everyone is a critic.

Of course, this isn't an excuse to be blasé either. There's also no shame in admitting you were wrong, even if you genuinely believed you were right when you wrote something. Only you can answer that. No one else should force you to say so. You should also be humble enough to take constructive criticism and feedback. This is another way to get better.

Having this balanced mentality will help you to move forward as a writer.

Whose Glory?

"So, whether you eat or drink, or whatever you do, do everything for the glory of God." – 1 Corinthians 10:31 NRSV

Though I strive to uphold this Scripture, it also makes me pause. Whenever I'm writing, whether it's a story, documentation, or this blog, this nagging question echoes in my mind: Whose glory am I doing this for?

Then, the answer comes or follow-up questions come. Am I doing this for God? Or am I doing this for myself? And if I say I'm doing it for God? Am I really? Or is that a convenient excuse I give myself to do what I do.

No matter how hard we try, we can't avoid this question. So we must honestly answer it.

This question isn't only for writing. It's everything. So why is this question important? Well, it'll steer us toward why we're doing something, including technical documentation. 

On the surface, technical documentation seems to glorify the organization. The organization tells its audience they have the answer they are looking for. If its audience is grateful or in awe over the information, the credit goes to the organization. But who wrote the documentation? If you're a technical writer for an organization, you wrote it or those on your team did it together. 

Now, if you believe your organization is the best and you're truly writing for it, then, by all means, do so. But are we deluded ourselves? Isn't there something we get out of creating technical documentation? Isn't there a sense of accomplishment or pride? You may be a better person than I am. When I create and deliver technical documentation, I get a rush and the satisfaction of a job well done. It's a great feeling when I get stellar feedback.

So, on some level, I'm creating technical documentation for my glory. Even when it's a team effort and I happily give credit where credit is due, I still get something out of being a part of a bigger effort. Also, I enjoy creating technical documents because I like helping my audience clearly see the answers they're looking for. Though I want to use technical writing to help put food on the table for my family, I like the feeling that I'm doing my part. So it seems inescapable that I'm doing all this for myself.

If we're completely honest with each other, you would say the same thing. So what do we do? Do we just admit we're really narcissists and live that out? If so, see where that takes you. Or do we strive for something better? 

I think the better road is to acknowledge this selfish element and strive to create documentation for God and others. Like writing, striving for this is a life-long goal. Even if we're far from this, it's worth pursuing. 

Though I'm far from perfect and I don't have it all figured out when I've asked God to help create documentation for Him and others, He has helped me create something far better than I could've imagined, especially when I've collaborated with rockstars in their fields.

Honesty with this question is the way to move forward. But be careful! It might lead to other questions, such as: Is this something we should be doing? If not, should we do something else that's not for ourselves? This includes technical documentation. 

To deepen ourselves in our trade, we must reflect on why we do what we do. Whose glory? Us, others, God?

Grateful For This Blog

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 another discussion for another day.)

When I first became a technical writer, the most stinging part initially was I had no byline. The document's byline was the company's. But I realized over time: It's not about me. It's about the company I represent and their customer. God has continued to use technical writing to show me of this fact. 

I would be lying to say I'm totally okay with this fact what we write isn't ours. But I can also say I have embraced this fact and it continues to make me a better writer. I realize what I do isn't about me. Sounds like a contradiction. It's just a lifelong process of accepting this.  I'll let you decide whether I am contradicting myself.

I have this blog because it's something I can call my own. I don't care if it gets a lot of traffic. I don't care to be famous. It's overrated anyway. I just wanted something where I can showcase my writing style. I am grateful for it. I also use it to help those who are on their journey with technical writing or even just writing in general. We are all writers, regardless of our stripes.

But ultimately, nothing I write is my own, not even this blog, my novel, or anything else I write. It all belongs to God. What I do should glorify Him. Technical writing just helped me see this eventually.

“(A Psalm of David.) The earth is the LORD'S, and the fulness thereof; the world, and they that dwell therein.” -- Psalm 24:1 KJV

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.

Show, Not Tell–Bring Documentation to Life

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 simplest approach. But if you do this with every single sentence, your writing might become flat.

Show: "Uoof," Toby cried as he went over a rock. "This is no easy cruise. Whoa!" Toby sharply turned the steering wheel of his rover to the left to avoid falling into a crater. "That was close! Just a few more miles before I get through this rough patch. I see town up ahead."

Here, showing adds dimension to what Toby's doing.  It's more than just writing more sentences and adding dialogue. Far from that. It's about painting an in-depth picture, especially if it helps the story along. 

But with all great pieces of advice, we can take it to an extreme. If we show everything, then we can get an overwritten mess, where you might overwhelm or confuse readers. You might end up with written pictures without any context to link them. Narration is telling a story, regardless how you look at it. Knowing where to show and where to just tell is tough and can only come through practice and time. The key with showing is using it where it better communicates you're trying to say.  

Showing in Technical Documentation 

One of the advantages with technical writing versus other styles is showing versus telling is easier to do. I'll explain how. Rather than crafting a narrative like the example above, you can use screenshots and other examples in certain parts of document. 

If a flowchart or a screenshots succinctly explains a concept or an action better than writing out paragraphs of text, then use the picture. The cliché "a picture is worth a 1000 words" is true in technical writing. 

If you're writing something like API documentation, then showing code examples and call responses will help communicate your point across. I would venture to say with API documentation, code examples and responses are more important than the writing itself. So, showing is crucial. For an example, see one from Square.

I would include hyperlinks in showing rather than telling, if they better showcase what you're trying to say. 

But you don't want to place screenshots, code examples, or hyperlinks just for the sake of doing it. You risk having a bunch of examples without context.  Doing so, might confuse and overwhelm your audiences. You want to place examples in your documentation because they better clarify information you're trying to convey. Knowing where to place visual examples instead of writing is key to good documentation. 

Showing examples through code examples, screenshots, and graphics will help your technical documentation come alive, especially with clarity. Sometimes, your audience might use your examples as a shorthand way to comb through the documentation. So, make your examples count.

We'll Hang up Our Pens Someday

Recently, Pat Buchanan said he was retiring his long running column. This blog is beyond the scope of politics, so I'm not interested in discussing Pat's stances one way or the other. I'm interested in this angle: We writers, regardless of our stripes, will someday hung up our pens. 

We will someday write the last book, last blog, last technical documentation, the last copy, the last whatever we do. We will all someday write our last word. 

If you say, I'm not hanging up my pen ever, well you don't have a choice. There might come a day where you're no longer able to write or you'll draw your last breath. In any case, you'll be hanging up your pen.

The reality is our writing pursuits and career have an expiration date. But we don't have to dread this impending end. If anything, it should give us more focus to write, since we only have so much time. One thing we can stop because it's an emotional waste of time is self-wallowing. You never be good as any other writer because you can't. All of us are different. Comparing each other doesn't go anywhere. So, don't do it! Also, if you keep talking about writing but don't write, then you need to make a decision. Is writing important to you? If so, write. If not, move on to something else. Writing isn't a glamorous pursuit. It's a hard road. To me, for now, it's worth it.

Finally, when we write we need to decide why we are writing. What's our focus and why. What's your passion? For me, I like technical writing because I like to help others and I want to bring glory to God through it. I'm planning to do this until God calls me to do otherwise, He returns, or I draw my last breath. While I still can, I want create the best documentation that I know how. 

So, write while you still can and know why you do it. We'll all have to hung up our pens, so make it count. 

Mark Up the Screen with Markdown

Markdown Logo

When it comes to writing on a device or a computer, I want something simple that allows me to focus on writing yet powerful enough for me to create full-on documentation or a book. Markdown fits that for me.

Markdown is a markup language that's basically simplified HTML. You just focus on writing without the other stuff and the rest follows.

There are different flavors of Markdown, such as kramdown. But, it's still Markdown. I have used Markdown to create some documentation or to communicate on a project's status in GitHub. When I did that, it felt pretty freeing to focus on what I wanted to say. Creating Markdown files in Atom for some documentation was pretty fun too. 

I'm even using Markdown to create an early draft for my next book. 

If I had my druthers, I would create all technical documentation in Markdown. I wish I could just do all my technical writing magic in this markup language.

Anyway, here are some places to get a good understanding on Markdown. (Thank you, John Gruber for creating Markdown. I appreciate it.)

I hope this aids you in your journey. Keep on writing. 

Daring Fireball

Markdown Guide

kramdown

GitHub Markdown Cheatsheet