Search This Blog

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.


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.