Search This Blog

Thursday, April 8, 2021

Grateful for the Little Things

Warning: The following post is not my typical thoughts on technical writing. It's some reflections on life. So, if you're looking for more technical writing related, please wait till next time or look at the previous stuff.

I'm grateful for the little things in life. 

I'm grateful for my family. I'm grateful for my wife. She's really a gift from the Lord. She reminds me of what's described in the book of Proverbs (e.g., Proverbs 18:22 , Proverbs 19:14, and Proverbs 31). I'm grateful for my children. As it says in Psalms 127, they too are gifts from the Lord. I'm blessed to have them.

I'm grateful I'm alive. I'm grateful I have food, running water, and shelter. These things many people around the world lack, while we take these these things for granted.

I'm grateful my health has improved over the past couple of years. There was a time it was painful to walk and had to go through physical therapy twice. Now, I can kickbox. Though much older and still have aches and strains and I'm nowhere any good at kickboxing, I never felt more stronger and in shape. However it lasts, I'll be grateful.

I'm grateful I had a technical writing career for over 20 years. Whether it'll continue, only God knows. I'm grateful for the experience of it, even with the pain, conflict, hangups, and trials that came with it. If it finally ends, then I would be grateful that I had a long run.

I'm grateful I published a novel. With my wife's help and the Lord's, I was able to bring a manuscript tucked away for so long into the light. Whether my works in progress get published or not, I'm grateful for the one I put out. I'm okay whether I put out other books or not. If not, then Lord willing, I'll find a way to continue to write.

I'm grateful I live in an area where it's freer than where I came from before. It's far from perfect and much more difficult to get to things I like to do. But I get a better peace of mind, more liberty, and more likely to encounter nature than where I lived before. These things money can't buy. So, I treasure them.

I'm grateful I got to pick up the guitar again after so many years. Though I'm nowhere near any good, I'm grateful I was able to afford a low-end acoustic guitar. But more so, my kids and I get to play together and make music. Doesn't matter how good. The fact I get to play and play with them is what I'm grateful for. I'm also grateful I can express myself through music.

I'm grateful for Lichess. Though I'm nowhere any good at chess, I'm grateful Lichess made an app that's made Chess accessible and on the go. I get to play more often, especially with the Chess puzzles. My kids appreciate playing Chess and some variants through this app with me. 

I'm grateful for coffee. I enjoy grinding own beans and the aroma from it. I enjoy  brewing a fresh cup and the taste doesn't disappoint. Like many technical writers and other writers, coffee is fuel to get me going in crafting my work. There's nothing like a good cup of black coffee. 

I'm grateful for this little blog. Though no one really reads this blog, I'm just grateful I have this tiny corner to write on. I'm happy to help those on their technical writing, or writing, journey. Though I'm ambivalent about technology and its effects it has on our world, I'm grateful technology has allowed me to create a little ole blog. If it weren't for technology, doing something like this would have been very difficult to do. I have no illusions about anyone caring what I have to say. I also have no illusions this blog ever take off. But, I'm just grateful I'm here. And if what I write here helps someone in a little way, then I'm just happy to help. Even if my technical writing career completely dies or if I never put out another book, I still have this place to write. So yes, I'm grateful for this blog.

I can go on but who wants to read an endless list? So, I'll leave you with a final but most important.

I'm grateful to God. I'm grateful that His mercy and grace allowed me and anyone else who's willing to enter into His Kingdom. I'm grateful for His salvation, which costed Him dearly. I'm grateful He continues to provide, even when it looks bleak. I'm grateful He allows me to continue to live another day. I'm grateful God sustains every moment of my being. I'm grateful of all the beauty He made in this world and beyond. I'm grateful for all He made and that He holds this universe together. 

I'm not blind to the fact this is a very broken and cruel world. But it won't do me anyone or myself any good to simply complain and let the anger fester. If I do, I'll become some bitter old man and will sour relationships with others, including with God. What good will that do? I'll just do what the Apostle Paul wrote in Ephesians 4:26-27 and be constructive with my anger.

Will being thankful for all the little things in life change the world and make it a better place? I doubt it. But it gives me strength to face life and how to better respond to it. 

Life is too short to squander on regrets, vanity, stupidity, or bitterness. I rather seek God's Kingdom, make my family a priority, do the best I can as a writer to help others, and be grateful for the little things in life. 

If it's just little things I get in life, then it's enough for me and I'm grateful for them. 
But maybe it's a mistake to call these little things.





Tuesday, March 16, 2021

You Know DITA

You know DITA? Note I asked this as a question rather saying it as a statement. If you know DITA, then great. If you don't, then that's okay too. Your technical writing career doesn't depend on it. (Some may disagree and they're free to do so. But I'm not them. And they're not me.) But, it doesn't hurt to peek into the world of DITA.

What is DITA

Darwin Information Typing Architecture (DITA) is a way to organize content around topics. With DITA, you can extensively map your content. This will come in handy, especially if you are doing some help authoring. Of course, this could go beyond help authoring. Imagine how this can greatly help our readers in finding or presenting the information they're looking for. 

DITA also helps with reusing content. So, you don't have to reinvent the wheel every single time. Talk about an obvious time saver.  

Often, the problem isn't the lack of content or documentation, it's knowing how you use it. DITA attempts to address this problem.

You want to know about DITA? Then, check these out:





If this isn't enough, you can check out Adobe's yearly DITA World.

Hope this helps. So when you say I know DITA, it won't be an insult.




Thursday, February 4, 2021

SUI, SUI

SUI. SUI. I don't want to get su-ed. Yeah. Yeah. Yeah. Yeah. Yeah.

SUI is not something that just rhymes with a name in a popular song. It also rhymes with GUI. 

SUI (Simplified User Interface) is something we technical writers should take note and embrace. SUI is a graphical means in upholding our mission: Using simple and clear means to introduce our audience to complex and intricate topics. 

SUI goes hand in hand with our craft. It's more than just a style of an user interface. There are principles behind it, which is why it caught my attention. SUI upholds the spirit of technical writing itself.

If you want to find out basic information about SUI and why it's useful, then check this out.


Wednesday, July 15, 2020

What's the Point of Writing

My goal as a writer is to clearly communicate a point to another. If I can do that, then I accomplished my goal as a writer. Everything else that entails writing is just gravy.

This should seem obvious for those of us who are wordsmiths. Others who practice this craft, who are far more skillful at this than I, might give a different or a much more articulate or more insightful goal than what I just wrote above. But, let those write out their own goal for writing. I'm just speaking for myself on what I want to accomplish with writing.

But what is writing anyway? Writing is simply communicating a thought in written form to another. It could be writing to yourself but that's still communicating a thought in written form. That's what writing is about. What about poetry or creative writing? If we boil it down, it's still communicating a thought or a point in written form. I'm not dismissing these beautiful artforms. (I have even delved into this form of writing by creating and publishing a novel.)  I'm simply making the point writing is a means of communicating of what's inside your soul. 

But this gets tricky when we're talking about business forms of writing. In that case, you're communicating what is inside that organization's soul (ha, ha) and we're just facilitating. At least, that's my take from experience as a technical writer. If we are writing in a business setting, then it would be know if that company's values match your own because as a writer you are communicating in the heart of that company.

Where am I going with this? I believe it's important to know why you're writing. What are we are aiming at? Writing for simply writing's sake is a waste of time. That's like firing an arrow without a target in mind. That's only dangerous but pointless. When we write, we must know where are writing for and why. 

Of course,  I don't merely want to write to make a clear point. I want to make that point to help others with whatever it is they need help with. And of course, the point should be honest. But, I won't be able to help that person with honest information unless I make a clear point.

What about passion? Yes, you should definitely write because you have the passion to do so. If you don't have a passion to write, don't bother. Otherwise, it will show.

So, I stated my point for writing. What's yours?


















Thursday, May 7, 2020

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. 





Monday, July 1, 2019

Why I Don't Talk Much About Tools and Tech

If you've read The Placeholder for some time, you may have notice I don't much talk about specific tools or technologies. This seems pretty strange for a technical writing blog. But there's a good reason why I shy away from such details. It's because these are just details that shift like the wind. I am more interested in the bigger picture of technical writing. 

There are some other technical writing blogs that may talk about these specific things. And if you're looking for these specifics, then go to them. But I intentionally created The Placeholder with a different angle.  

I created The Placeholder because I felt the principles of technical writing were getting lost in the seas of ever-shifting currents of tools and technology and in the mire of the aspiring technologist. When I saw the ever-growing requirements for technical writing jobs to know such and such tool and you must know such and such programming language rather looking at years of writing experience, I felt technical writing was morphing into something it's not. I created The Placeholder to be a small (probably quixotic) bulwark against this ever-growing tsunami of technological requirements and other obscure oddities for a writing job.

A technical writer is a writer, first and foremost, who documents about how certain technologies, products, or services work. A technical writer is not a technologist who merely writes. That may offend some for me to say this. But when you strip a technical writer of their odd exterior, that person is a writer underneath.

I have no interest in writing about things with a short shelf life. I am interested in writing about things that will last. Principles, if they are good, will last. But virtual tools and technologies change with the direction of the wind. For example, when I first started as a technical writer I used Pagemaker. Then, the hot tool to use was FrameMaker. FrameMaker was a great tool to use for creating big technical documents. I used to create technical documents with a lot of equations that were thousands of page long. I was even FrameMaker's defender when the powers that be at a company I used to work for suggested shifting over to Word. I told them no because Word, at that time, didn't have the capability to handle the technical documents we were doing. FrameMaker was the go-to tool for a technical writer. If you were doing help-authoring, at that time, you would use Robohelp

Now fast forward, FrameMaker has lost its preeminence. Also, where's Robohelp these days? Many are requiring InDesign to create technical documents or use Wordpress for bloggish-type technical writing or maybe for help documents. By the time you get a handle on a platform or tool, it shifts to something else. It's almost hopeless to stay completely current with this. But tools are tools. They are not essential to technical writing itself. What's essential is quality writing. 

Principles of good technical writing stay about the same. Principles like active voice, concise language, and presenting information where it's easy to follow stays the same. And these are the principles technical writing should be built upon, not upon tools or technology. They have been here before I became a technical writing. They will last when I am gone. But I also recognize technical writing principles don't stay frozen in time and that's fine, they shouldn't. These principles should evolve when needs arise. For example, more recent concerns like greater accessibility to documents for those with impairments. We should incorporate accessibility into the "technical writing rubric" because we need to make documents that are accessible to as many people possible. These are the things I care to write about.

Technology is a double-edged sword. So, I am not so interested in singing praises about any particular tool or technology. There are two only reasons why I enjoy technical writing. One, I get to write. Two, I get to help others. If the technologists want to take over the technical writing world and push folks like myself, then I will take my two passions elsewhere. If God makes it clear for me to leave technical writing, then I will graciously bow out. Otherwise, I will stay in it. And while I'm here, I do what I can to create quality documents.

As for programming or markup languages, I don't mind talking about them. Like the written language, they evolve but the principles stay the same. Like the written language is behind good pieces of literature, the programming languages are behind some helpful pieces of technology and software. In recent years, I have taken a liking to Markdown. I am happy to see some technical writing jobs out there now asking for those who know Markdown. I like Markdown because it helps focus on creating good writing, not get lost in the trappings of tools.

So if I am not writing about the latest such and such the STC is talking about, it's because these things fluctuate. They can do that and that's fine. But, I will do my own little thing here. Remember, tools change but principles of good technical writing stay the same.

Focus on your craft and learn how to best the serve the audience you're writing for and the rest will follow.

Friday, June 21, 2019

Barriers to Entry

DISCLAIMER: This post is not authoritative. These barriers are merely one that I have encountered. These barriers (or perceived barriers) are based on my own interactions and the solely the opinions (possibly the mad opinions) of this writer. 

Photo by Travis Saylor

There seems to be a lot of technical writing jobs out there. But, it seems many technical writers, such as myself, are spending more time trying to get the next contract or job more than we have work itself. Many times, it seems we're either very busy documenting away or in between projects looking for work. Sometimes, it's for a very long time.

It would seem technical writers, such as myself, would get a job or a contract right away with the plethora of supposed opportunities out there. But, this doesn't seem to be the case. 

I've seen the same jobs or contracts posted for months. I've also ran into other technical writers who have been out of work for extended periods of time. Based on my interactions, it's not because they're bad at the what they do. There seems to be other factors. It seems to be there are barriers to entry for us technical writers to get a job or a contract.

Despite a few articles on the Internet that say technical writing is dying, that doesn't seem to be case. If any organization based their decisions to let technical writers go because of this, then they're sorely mistaken and misinformed. Actually, it would seem to be the opposite.

According to the The Bureau of Labor Statistics (BLS), technical writing is growing. According to their projections, technical writing is growing faster than some other occupations.  Also, according to the US News and World Report, technical writing is one of the best jobs for 2019. But it's quite possible these projections are flawed.

But the fact there are abundance of jobs, especially in tech, seem to show us technical writing is far from dead. Also, the fact there's a constant deluge of products, services, and innovations flooding society, so the possibilities to documenting them seems endless.  So, what's going on? What are the possible barriers?

Ever Growing List of Requirements


One barrier would be an ever growing list of requirements to get a technical writing job. Some of these newer jobs seems to be either something for programmers or the scientist. This would be acceptable except the technical writer is just a writer at the end of the day. Though, I believe writing what you know is very important, when did the technical writer become the sole realm of the academic elite. I would like to know when that was.

If technical writing is really belongs to these elites, then I guess I have been blessed whenever I got jobs. If one from such a priest class wants to explain me that I must have X,Y, Z piece of paper or I must an engineer or a scientist or whatever role of you approved of, then I will gracefully bow of out technical writing. But don't expect me to give up on writing all together.

Misunderstanding the Role


There seems to be a misunderstanding what technical writing is. It's not a scientist or a programmer who write. It's a highly trained writer, regardless of education or background, who break down complex highly technical information into easy-to-read prose. Unfortunately, many technical documents are so murky that nobody understands them. And throwing scientists or programmers into the task of documenting them muddies this even further.

Why do I say this? It's because SMEs might overlook some critical information when creating step-by-step information.  They assume their audience will know what they mean or imply. You can't do that with technical writing. You need to spell out each step. You may not need to define the terms because of the audience you're writing for should know, unless it's something new.

When you're showing someone how to do something, you need explain this clearly and one step a time. SMEs can miss needed steps and so can the technical writer. To see how daunting a task it is to document something step-by-step, check a previous post called Count All the Steps.

As a technical writer, you need to be the independent pair of eyes to break this information down, so you can catch the blind spots the SMEs overlooked. In my experience, though interviewing SMEs help give me information on creating a document, there are still gaps in it before it's complete. What the SME gives you is a starting point. You need to go through the software or the product yourself to document how to use it before you say the document is done.

Also, there are many different name for technical writer. Sometimes, they are called documentation specialists or even document engineers. It also doesn't help it seems organizations are using Instructional Designers to do a technical writer's job.

No disrespect to the Instructional Designers out there, but they are not technical writers. While the two occupations overlap quite a bit, they pursue two different goals.  I have had some who asked me if I have done instructional design and I had to say no. I'm a technical writer, not an instructional designer. So, this adds to the confusion.

Too Niche Orientated


It seems technical writing jobs are getting very niche orientated. But how can you get into them unless you get the experience? Even if you have the degree of that niche, there's no guarantee you're going to get that job.

Let's talk about tools. It's a tall order for companies to expect technical writer to know every tool out there. It's impossible. And if a company wants to shut good writers out because they don't know some arbitrary tool that not everyone uses, then they will be looking for a long time. (I guess that's the point with some of these folks.)

I feel the SMEs are dictating the terms of what they want as a technical writer and want a carbon copy of themself rather than looking for a good writer. You kind of have to wonder why many instructions and technical documents are horrible.

Any good technical writer will pick up any tool, programming language, or subject that comes their way. It's intrinsic for technical writers to adapt to any situation. If any technical writer tells you otherwise, then they need to get out of the field. Give us a chance!


All About Keywords


As for resumes, what many organizations or recruiters is look for certain keywords. Some say they don't seem to looking at cover letters either way. However, some say they do. Who's telling the truth? I have no idea.

In any case, many just use Applicant Tracking Software (ATS) to scan for keywords. So, they don't bother to look at the resume. The simple fact of relying software for certain keywords rather looking at someone's experience is another barrier.

They are reducing us to keywords rather than treating us as people. You even have articles that encourage you to use keywords in your resume so you can picked up by software. While using the right keywords will help your resume stand out, keywords aren't everything. We should be looking at the person's experience. A resume is a story of that person's experience. To simply look for keywords is degrading people and their story. This is wrong! But the moment we refuse to be reduced to mere keywords, the moment this barrier will come down.


Enough with NDA Fears


There's a bigger barrier and that's the problem of Non Disclosure Agreements (NDAs). While I understand why an organization would want us to sign an NDA, it's also not helpful for us because we, technical writers, would like to use samples of our work when you kick us to the curb at a moment's notice. (That's for another blog to expound why organizations are cold like this.)

We would like to show our work when other organizations are asking to provide samples. One time, I was speaking with the recruiter for a prospective contract and he was asking me for a sample, I told him I couldn't provide a sample because of NDAs. He told me the technical writers he interviewed said the same thing. 

While an NDA may not prohibit from sharing a sample, we also don't want to take the chance of getting sued by a company. Though the company may not have a leg to stand on from barring us from sharing a sample, an NDA is uncertain territory on whether we should have samples. I don't want to take the chance of finding out. My peers have seemed to have also taken the same overcautious road.

Unless you're writing internal or confidential information in an document, there's no reason for us to be barred from sharing a sample.

If you have a user guide going to your customers, then we should be able to share this since this is external communication. Perhaps, when technical writers have to sign NDAs, then there should be some exceptions for those who are in communications positions (such as copywriters or technical writers) in an organizations that we can share samples when our employment or contract ends. As for internal (not confidential) communication, we should be able to share this document with important information redacted from it. 

And from the organization's standpoint, I understand why they would want samples. They want to see how we do our work and if it's quality to them. I get it. A resume isn't enough. How can they trust we can do the job if they can't see it. 

Journalists, writers, photographers, and freelance copywriters have portfolios to show their work, why can't we. (There might be some technical writers who do have portfolios. And if you're one, then what I said doesn't apply. If you haven't gotten harassed for a portfolio, then I guess most of us are probably operating under unfounded fear and hurting ourselves in the process.)

Rethinking the Entire System


While this last point may not be a barrier per se, it might be causing problems. The whole idea of contracts and in-house technical writing might be adding to the barriers. 

These companies get to dictate the terms, make us fit their mold, and when there are done with us, they are discard us like we're trash. As far as independent contract gigs go, let's just be honest. It's really a nice way of calling us temp workers or you're a worker where the labor protections don't apply.

These companies are trying to make us feel like we're independent but we are really exploited by them. It's a devilish illusion!

It also doesn't help we have to compete with cheap labor from content farms or the like. Makes me so angry that they writers pennies for a lot of work. (But that's another post for another time.)

So what do we do? Let me offer some suggestions. Perhaps, technical writers should be in the realm of self-employed artisans. We should also somehow band together to form cooperatives or guilds so we can have the power to break down these barriers. Some might point out The Society of Technical Communication but it's just an association. It's not a force with teeth. 

If we band together in an organized fashion, like many workers have had to in the past, then we get to tell these organizations what it means to be a technical writer. It's not because we are the end be all. It's because we are ones doing the writing.

Though we need to serve our audience by creating the documentation that meets their needs, we also need to set up clear boundaries what's required to be a good technical writer. And what's required to be a good technical writer is this:

  • Excellent written and oral communication skills.
  • A willingness to learn new things, 
  • A servant's heart.

I don't know. Maybe it's time for us technical writers to rise up peacefully yet boldly to smash all these barriers to entry.

If someone is reading this, I hope you can get this conversation going. If you can better identify different barriers or better articulate them, more power to you. I'm trying to do my part to save technical writing.

Writing is a craft, including technical writing, and we should guard it as such.