Technical Writing: Systematic Advantage

When my wife and I watch campy movies, there's a typical theme of a writer who has writer's block. The writers in these movies try to write something but can't. Or when they start writing on the computer, they let out a sigh, deleting everything till it's a blank screen. While these scenarios are exaggerated, there is some truth to it.

It's difficult when you must create something that relies on your mind. I know. I've written a novel before. Writer's block is always lurking around the corner. When you write, that constant inner critic is always trying to lead you to that corner. Those who are career authors, I don't envy them. God bless them for keeping their imagination going, though they struggle to craft meaningful words on the pictures they're trying to paint.

We technical writers have a systematic advantage over our creative counterparts because we document things based on what we can see and use. (I mean systematic, not systemic because while the writing process is universal, we're in a different category than creative writing. I suppose you could say we have a systemic advantage. In any case, we have an advantage.) If you're documenting user interfaces, we can walk through each step of the way to help us write. So the chances of writer's block decrease, though it can still happen.

Should we feel ashamed that we do have this over other writers? Absolutely not! But we should be thankful that we don't have those blocks. Of course, our blockers are from SMEs, developers, or whatever. We can't write anything until they're removed. But once we remove these blockers, we are to free to write till we're done. Our blockers are external not internal, so we have an advantage. So let's use it to create great documentation. Since we don't suffer writer's block like the creatives, there's no excuse for sloppy documents. Am I saying perfection? No! There's no such thing as perfect documentation. But we can strive towards excellence.

So, my hat goes off to you creatives for doing what you do. Keep writing! Thank you for building those worlds for us to enjoy and think about.

 

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?

When you Doc as Code

What is doc as code? Doc as code is basically two things. One, it's creating documentation with the same tools as you would use to create code. Two, it's using similar methods of creating, versioning, and publishing documentation as you would with code. 

What do I think about this? Short answer is context. If you're creating or editing material in a software environment that uses Agile methodology, then you should doc as code. Otherwise, I wouldn't worry about it. If you're in this context, I'll give you a few,  brief reasons why you should doc as code.

Save Costs

The first and foremost why you should doc as code is to save costs. Tools, licensing, even training on how to use tools all cost money. It also costs time to maintain and invest on different tool sets. If you're using the same tool to create code and documentation, you can save on both. No further explanation needed. 

Easier to Build Bridges

If you're using the same tool as your Subject Matter Expert (SME), it's easier to build bridges to create documentation. If you're using the same tool(s), it's easier to collaborate together on documentation. This doesn't mean you have to learn to code. (But it might help to know a little bit.) In some ways, using the same tools and releasing documentation the same way as code is like you're speaking the same language as your SME.

More Unified Experience

If you doc as code, then the release of software and documentation is much easier. The obstacle of getting your documentation in a certain format, so it goes with the software release is no longer an issue. You just have to make sure you and your SMEs are working in sync to make sure the documentation reflect what's in the code and vice versa. And that can be challenge in itself, so why would have other unnecessary issues to prevent this from happening.

To find out more about doc as code, check out these resources:

https://www.writethedocs.org/guide/docs-as-code/

https://www.gitbook.com/blog/what-is-docs-as-code

https://github.com/readme/guides/code-as-documentation