May/June 2019

Learning New Skills to Solve Old Problems

By Jeanine Meier

You know the saying about working smarter, not harder? There are many potential benefits, such as better work/life balance, more enjoyable work, and sustainable productivity. But what if you take it a step further by working smarter while expanding your skills?

Often, when we think about working smarter, we think of using the tools we already have in our tool chests, but in more efficient ways. But is that really the best solution? If you have two days to tear down a house, do you want to swing a sledgehammer—even with a perfected swing and knowledge of where the load bearing walls are—or use a bulldozer? Well, if you’ve never used a bulldozer, the sledgehammer may seem like the wisest choice. But what if we take a chance on the new skill? Learn how to drive that bulldozer on day one, and then tear down the house on day two? It is a risk, but the rewards could be immense.

Analyzing the Problem

Before you can find the tools to relieve your pain points, you need to fully understand what you are trying to solve. Start by breaking a problem down into component issues. This not only makes the problem less daunting, it can help you find solutions that work on problems that might seem completely unrelated.

I am a technical writer with assignments ranging from developing documentation for enterprise software to preparing online help content for translation and then reassembling the translated help for release. The online help is translated from one type of HTML Help, which then needs to be converted to a different help type for installation with the software. We deliver well-formed HTML to the translators, but the content they return is not well-formed, which causes the conversion build to fail. Thus, when a translation is complete, I must fix the things that are broken and build the new help; the steps are always the same and can be really boring. I’m not a fan of boring.

I took over these translation tasks from a technical writer who departed for new adventures, and I immediately thought, “There has to be a better way.” The search for a better way started by analyzing what types of content broke the help and what characteristics they shared.

Problem: Translated content breaks online help.

The translated HTML had character entities that were incompatible with the script that builds the final help package. My first thought was that we should send it back to the translators, as they introduced the character entities that broke the build, but, alas, that was not an option. The solution I landed on was to use the Find in Files command in Notepad++ to search through the HTML files and replace the character entities with an applicable substitute.

Problem: Translated HTML was no longer well-formed, which caused the build to fail.

The translation process removed the closing forward slash (/) on image tags in a file that had hundreds of lines. To solve this problem, I needed to add the forward slash. Turns out there are a lot of closing angle brackets in a large HTML file. I couldn’t just stick a forward slash in front of them. So, I looked for something more precise, and found that I could use regular expressions to find the end of the image tag and add the forward slash without altering anything that came before it.

<img … href … translated attributes … >

Regular expression search:


(<img([^>]*))

Replace with:


$1/

For example:


<img alt="目录结构树控件" class="helpImage"
id="imgHelpNodeC1/F1_BP01UserInterface.html"
src="images/plusHelp.gif" title="目录结构树控件">

will change to:


<img alt="目录结构树控件" class="helpImage"
id="imgHelpNodeC1/F1_BP01UserInterface.html"
src="images/plusHelp.gif" title="目录结构树控件"/>

Turned out that regular expressions were the solution to many of the issues with the translated content. I had used regular expressions frequently over the years, but when I started to write the solutions for these issues, I realized that my understanding of complex regular expression was not up to the task. I initially asked a developer to help me write one of the regular expression solutions, but I kept finding permutations that weren’t addressed. Rather than repeatedly asking for help, I realized that the better solution would be to learn to write complex regular expressions.

Learning opportunities

To beef up my regular expression skills, I signed up for the Regular Expressions class on lynda.com. I wouldn’t say that I became a professional regular expression developer just from watching videos and doing exercises, but I learned the syntax and was able to create regular expressions to solve the problems I was encountering.

Never has the need for continuous education been met with such an abundance of training resources. From blog posts to training videos to free college courses, the internet has democratized learning.

  • YouTube tutorials cost a couple minutes of your time to watch an ad or ten bucks a month to subscribe.
  • You can subscribe to a service like Lynda.com or purchase courses on Udemy. (One note of caution: Udemy course specials are to us studious types as Black Friday is to Christmas shoppers.)
  • Online college courses come in a variety of flavors from freely available recordings to extension courses to graduate level programs.

These opportunities allow you to increase the tools in your tool chest, improve job performance, and have something to add to your resume or LinkedIn profile.

Back to Problem Solving

What do you do after you solve a very specific issue, such as a missing closing forward slash in a file with hundreds of lines of code? Watch for the next opportunity to use the skills acquired to meet that challenge. For example, you learn that the product you are working on is being rebranded, and every instance of the product name, acronym, and even some tools within the product need to change across multiple documents. You now know that you can use regular expressions to match some fairly complex patterns and Notepad++ is really good at finding content inside of files in selected directories, so you pull out the regular expressions, fire up Notepad++, and solve the problem.

Unexpected Benefits

Early in my technical writing career, I worked at a software company that developed power distribution system software, and that was founded by electrical engineers. I have a degree in biochemistry and had been working in medical research for several years, so I felt comfortable with the complexity of the software. Unfortunately, there were skeptics in the ranks. I won over the doubters by demonstrating abilities beyond what they expected. For example, when a project team was behind schedule, I volunteered that I could help write SQL statements, and when the marketing team was preparing for a trade show, I showed off some newly developed animation skills with a demo scenario.

My credibility and confidence soar when I indulge my passion for learning stuff. You can’t go wrong doing the same.

Jeanine Meier (jeanine.meier@oracle.com) is a Technical Writer and Curriculum Developer on the Oracle Utilities Knowledge Management team. With more than 20 years’ experience in technical communication, she has an extensive background in information design and development. While primarily focused on software documentation, she has worked in pre-sales and marketing communications, implemented proposal automation systems, and developed web sites. She is a sought-after consultant focusing on information design and messaging. She is an avid learner with a passion for process improvement.

Download the Sept 2019 PDF

2019 PDF Downloads

Sponsor

Sponsor

/* ]]> */