Why I Love Being a Tech Writer#

I often feel like I’m lucky for choosing a career that I (90% of the time) enjoy. When you’re young, in college and trying to figure out what you “want to be when you grow up,” often the choices are overwhelming. Maybe that’s why I took the long route (8 years) to complete my degree. I dropped out then went back part-time while working full-time in an effort to figure out what I wanted to do. It worked and (luckily) I was already on the right path with my current major (English).

 

I still feel like I got lucky – I choose a career that I’m genuinely passionate about. Some days you’re excited about getting that next project done or relieved that you’ve finally figured out to present a difficult concept. Other days, work is, well, work. You go. You write. You go home and do something more fun. (Writing is not always fun!)

 

This morning, I wasn’t sure what type of day it would be until about half way through my morning document development meeting. As I’m scribbling away on my note pad, trying to write down everything the developer was saying I was struck by one of those “This is why I love my job!” moments. Honestly, at this point in the meeting, I really had no idea how I was going to put all the information together. I was still struggling with understanding the concept. It was all slightly overwhelming.

 

Yet, I was loving it! I had a new, challenging puzzle to solve. (I’m fascinated with understanding how things work. One of my favorite TV shows is Modern Marvels on the History Channel because they take you behind the scenes and show you how things work.) As the development team talked through the concepts, drew and re-drew diagrams on the board, I frantically copied everything to my notes as well as chimed in to ask a few questions. 

 

I have to admit as I walked out of the meeting I was still feeling overwhelmed. I had a basic understanding of the overall process and about six pages of notes about how all the pieces and parts fit together, but there were still a lot of loose ends and questions. Walking down the stairs back to my work area, I began thinking about how to present it. This project would be a fantastic candidate for a more interactive, online document where I could show the progression between each stage. Unfortunately, I’m limited to a static, PDF for the final version. Hmmm, that’s one puzzle to solve.

 

The second puzzle is how to explain all the information without providing too many details. One of the issues with the current documentation is that it provides too much information. The developers are getting confused; they’re asking too many questions because there is so much background information included. I need to present just enough information to explain the overall process but not too much. That will be a challenge.

 

Ultimately, I have to understand how everything works so I can present all the pieces and parts together into a coherent, useful document. That’s a challenge I always enjoy (partly because the process of organizing information is a puzzle in itself; it’s also because I love organizing things – just ask my husband out our linen closet.).

 

Challenges, puzzles and learning how things work – today those are just a few things that I love about being a tech writer.

 

 

 

Have you got a documentation puzzle to solve? Contact me! I’d love to work with you to understand and present the information in a way that’s beneficial to you and your business.

Wednesday, September 23, 2009 11:50:46 AM (Central Standard Time, UTC-06:00) #    Comments [0]  | 

 

Oh, no! Another Acronym: Understanding IOB#

In general, I’m always thinking about how to “prove” the documentation I craft adds value for the organization. Does it impact the bottom line? Does it reduce support costs? Does it promote employee efficiency? Plus, many clients feel conflicted about documentation, it is needed within their organization, but it’s hard to justify the costs especially in today’s economic climate.

 

This morning I was reading “Measure Smart: Trade ROI for IOB” published in this month’s edition of CLO magazine. At first, I was simply curious, “What is IOB?” Turns out, IOB, or Impact on Business, is an extension of ROI. Whereas most traditional ROI measurements focus on pure numbers, IOB looks at direct linkages between (in this case) training programs and business programs. Instead of looking at the total number of people trained, IOB focuses on changes in performance metrics after an employee completes a training program.

 

For example, say a customer service employee takes an interpersonal communication course. After the course, the number of complaints they receive are reduced (and they actually get a few compliments). Using IOB, the training department could say that the communication course improved that employee’s performance. They now have a more direct link between training and performance.

 

As I was reading, I thought the same concepts could be applied to technical writing. Like training, tech docs seek to convey knowledge to readers with the goal of teaching them something. And technical communicators are interested in those same metrics as training professionals – providing direct linkages between the documentation and business initiatives. “Hmmm, interesting,” I thought as I filed this tidbit of information away (for the next time a client asks about how we can do this).

 

The article also got me thinking about the future of technical communicators. As our field continues to evolve, we’re seeing a shift from printed documents to dynamic content. I have a feeling that in the coming years, technical communication professionals and training & development professionals will find more and more common ground as they face these similar challenges.

 

This is an exciting prospect! I think it will open new doors for all of us, especially those (like me) who enjoy elements within each discipline. I also think the increased collaboration between these two professions will enable us to develop more unique and concrete ways to evaluate the effectiveness of the materials we produce. Maybe, just maybe, IOB is the first step toward this future vision.
Thursday, August 06, 2009 11:18:06 AM (Central Standard Time, UTC-06:00) #    Comments [1]  | 

 

Help! I'm Lost in this PDF!#

I have a rant. Why do I keep coming across PDF files that are not accessible? How do you expect me to navigate through a 133-page document that does not include a TOC nor does it include PDF bookmarks? I’d really prefer NOT to scroll page by page slowly scanning the headings for the topic I’m interested in. Wouldn’t it be easier (especially since you created headings in the first place) to simply add bookmarks? Please, I’m begging you. I’m cross-eyed from all the scrolling, and I think my mouse is going to go on strike. It likes to click not scroll.

 

Now, I’m not arguing that all PDFs should be 508 compliant (although this would help). All I’m asking is for a little help. Bookmarking is one of the easiest things you can do to help make your PDF more usable. Especially if you used Word to create the source document, adjusting the conversion settings to bookmark your heading styles is a snap. (What? You didn’t use Styles for your 133-page document! That’s a whole other topic to explore.) For now, let’s pretend that you used Styles and move on….

 

Before you convert the document though Adobe Acrobat (I’d recommend using the Word plug in to more easily control what’s converted), click the Adobe PDF menu then choose Conversion Settings. Click the Bookmark tab and check (or uncheck) each Style you want converted to a heading then click OK. Poof! You’re ready to create your bookmarked PDF. Let Adobe do its magic and marvel over how all your headings are now conveniently accessible from the bookmarks panel in Adobe Reader. Isn’t that easy?

 

Now for accessible text. I’ll admit; this can take a little more work. If you’re working in Word, Adobe will automatically convert all hyperlinks in the source document. This means all your references and hyperlinks are automatically converted! It can’t get any easier than this. (You should check them before your conversion to make sure they navigate to the correct spot. Word sometimes anchors these incorrectly.) 

 

If you’re working in Adobe InDesign or QuarkXPress, you’ll have to set up each reference link. The nice thing about these programs is that you can set up one “link style” then apply it each time you need that link. This is extremely handy when your document has the same link sprinkled throughout (such as a website or email address). When you’re ready to convert, Adobe Acrobat will automatically convert all your links during the PDF-ing process. Ta-Da!

 

See how easy it can be? Why not give it a try? Maybe your mouse is more like mine – more clicking, less scrolling, especially when it comes to 133-page PDFs.

Thursday, July 16, 2009 8:03:56 AM (Central Standard Time, UTC-06:00) #    Comments [3]  | 

 

Reader-Centric Document Templates#

A client recently asked me how I go about developing documentation templates. What principles guide my designs? Where did I learn how to design templates?

 

At first I didn’t know how to answer. Document layout techniques come naturally to me. Yes, I’ve had formal training on layout, font and color fundamentals. I do believe those help guide my design decisions; however, I often vary from these guidelines mostly to aid readability. Overall, I have one principle I adhere to when I’m designing templates:

 

Make sure the reader can use the completed document efficiently and effectively.

 

How I go about doing that is different for each client because each audience has its own unique characteristics. During your design phase, consider the following elements:

 

  1. How will the document be accessed (online vs printed vs both)? Choose fonts, colors, and layout characteristics that work best for that medium.
  2. If the document will be printed, is your employer/client doing the printing or the reader? This will affect your use of color, fonts and graphics as well as limit the page size.
  3. What information is the reader looking for on the front page? Some documents may need a formal cover page while others may be more usable without one.
  4. How will readers be referencing information within the document? Use organizational features such as a Table of Contents or Appendix to help readers find what they need quickly.
  5. Finally, what other information must the document include? Incorporate information such as a document ID, publication date, security notice, etc. into the format so that it is not a distraction to the reader.

These are just a few things to take into consideration when designing a new document template. Be open to changes (even if you’ve been using the template awhile) and flexible with your design. Like the rest of the documentation process, templates change as the business and content needs change.

Wednesday, July 15, 2009 3:44:24 PM (Central Standard Time, UTC-06:00) #    Comments [0]  | 

 

Technical Writing as a Noun or a Verb?#

Technical Writers are not unique in their struggle to prove they “add value” to an organization. Currently, I’m working for a large, global client in their Enterprise Architecture division. While this client’s main business is not software development, because of the scope of their business they have invested significant resources to support the IT infrastructure and software they need to efficiently conduct their business efforts.

 

My current team’s challenge within Enterprise Architecture is helping the rest of the global organization understand what they do and why they do it. (Sound familiar?) Today, I was reading through some documentation about Enterprise Architecture based on research Gartner conducted. The particular document that caught my attention was one that was trying to provide a definition for Enterprise Architects.

 

The definition they crafted was well done – logical and comprehensive albeit a little clumsy simply because of the length (but at times you simply can’t avoid that). As I completed the paragraph, I thought they’d covered it all. Then they proceeded to explain that they needed to clarify a few points because of feedback from some of their customers and analysts.

 

As I read through their clarifications, I kept returning to the first point they stated: Their definition looks at an Enterprise Architect as a verb (i.e., someone who does something) rather than a noun (i.e., someone who produces things). I thought this distinction was significant, both to Enterprise Architects as well as to Technical Communicators.

 

It’s long been known that Technical Writers are most often viewed as “expenses” rather than “revenue generators.” While, in most cases, this is true, this view by the organization overlooks all the value that (good) Technical Writers bring to the table. Based on the Gartner article, I also have to wonder if some of this image is perpetuated by the fact that as writers, we are very focused on deliverables – concrete documents that prove we’ve been doing the work we say we’ve been doing. But what if there is more to it than that?

 

The Gartner article states (in the context of Enterprise Archicture):

“Our definition of enterprise architecture has focused on the ‘verb’ – because we feel it is important to emphasize the fact that enterprise architecture is a process. That is important because we find that often, when people focus on the outputs (‘the noun’) rather than the process, they tend to be more concerned about producing a predefined set of deliverables than they are about meeting the strategic imperatives of the enterprise. This single-minded focus on deliverables is a mistake because it can lead to mountains of ‘artifacts’ (requirements, models, principles, guidelines, standards) that are not necessarily connected to the strategic imperatives of the enterprise and are therefore not leveraged across the organization.”

 

Hmmm, that sounds an awfully lot like what we often do as Technical Communicators. Let’s look at this a little closer.

 

Technical communication is a process, something we engage in whether or not we produce anything. Think about all the time you spend talking (and listening) to people within your organization. We communicate technically when we work with users, editors, developers, HR or any individual within an organization. In that context, we are engaging in a process – we are communicating technical and non-technical information to an audience. Yet, when it comes time to relay to our boss what we “do” we often forget about these essential, daily actions.

 

We get bogged down in the numbers – completed documents/projects, new document initiatives, the total number of documents available to your organization. When passed up the chain, these numbers are just that, numbers. There is no direct correlation to the business. Thus, it’s easy for those removed from the process to discount what we do (produce documents) and eliminate that position so that funds can be reallocated to a department that easily shows direct impacts to bottom line business (such as sales). So what do we do?

 

I think we look at our positions at Technical Communicators more like Gartner looks at Enterprise Architects. Our job is not to produce but to facilitate. We are facilitating technical communication through documents, presentations, formal and informal conversations, company-wide standards, etc. We do more than just write – we assist the business with communication that supports the overall enterprise goals and objectives.

 

When we look at our jobs that way, it becomes much easier to align our daily activities with strategic corporate initiatives. We did not write a document simply because we were asked (or told) to. We crafted that communication to provide the sales team with an additional tool for their new sales strategy. We created that user manual, help text or tutorial to provide users with a reference tool which, in turn, cuts down on help desk related calls. We standardized how documentation is managed to help internal employees save time when searching for the reference they need.

 

By viewing ourselves and our role as active, verb-like participants, we not only help justify our place in an organization, but we also help make ourselves indispensible. So the next time you get bogged down in deadlines and document metrics, stop and ask yourself: “Are you a noun or a verb?”

Source: Gartner Clarified the Definition of the Term 'Enterprise Architecture'; Publication Date: 12 August 2008; ID #G0016559

Wednesday, July 08, 2009 6:40:41 PM (Central Standard Time, UTC-06:00) #    Comments [0]  | 

 

All content © 2010, Libby Craver dba Written Designs
On this Page
Calendar
<September 2009>
SunMonTueWedThuFriSat
303112345
6789101112
13141516171819
20212223242526
27282930123
45678910
Archives
Topic Categories
This Site
Disclaimer

Powered by: newtelligence dasBlog 2.1.8102.813

The opinions expressed herein are my own personal opinions.

Send mail to the author(s) E-mail

Theme by Libby Craver (Based on Essence theme by Jelle Druyts)

Sign In