... in the world of Technical Communication

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.

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.

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

Long-gone are the times of endless (and excessive) spending – on both a personal and corporate level. As we tighten up our pocketbooks and purse strings, corporations are also analyzing the ways they spend money – specifically as it relates to training, development, and documentation. While some view this as threatening (“They’re cutting my budget so much I can’t do anything!”), I think this is a much needed shift in corporate culture. As professionals, we should be responsible for showing how our efforts impact bottom-line business. So how exactly do we do that?

First, we have to get past the notion that ROI, or Return on Investment, metrics are a bad thing. ROI, in essence, is what justifies our positions as leaders within our fields. I think the fear of change is behind most people’s aversion to ROI. If looked at from a positive light, gathering metrics that show the program’s you’re implementing have a direct impact on the business gives you (and your department) tremendous power. Now, you not only have the ability to implement training programs, but you have a way to measure a program’s success. Imagine walking into an executive committee meeting with a new idea and being able to justify it with hard metrics (actual dollars & hours saved) and soft metrics (employee satisfaction and growth). See the power of ROI?

“Ok, ok,” you say, “That’s a nice ideal, but how do you actually measure those things?” Here’s where it takes some creativity and lots of planning. At the outset of the project, you MUST determine what you’re going to measure. ROI figures will not be accurate unless you figure this out before you even start. You have to take a snapshot of the business BEFORE the training program or documentation project is initiated so you have a baseline.

Then, you must keep track of the costs (effort as well as dollars) it took to implement the program. Sometimes this is straightforward. Other times, you have to look creatively at how to collect this data. Once your development is done, you must have a solid plan in place for the roll-out of your new program. Document your plan and your progress (you can use this later to help you structure other programs.) This roll-out plan should also get factored into the overall “cost” of the project.

Finally, you have to wait and measure. I know; this is always the hardest part! Because of the nature of training and documentation, cost benefits are not realized overnight. Sometimes it takes weeks, most times it takes months, and for some projects it takes years. Be prepared and ensure your management team is prepared to take the time needed to accurately gauge whether your program was successful.

As your program becomes part of your company’s culture, continue taking baseline measurements at regular intervals. Are your metrics different one month, three months, nine months after the implementation? Taking periodic measurements not only helps you chart savings, it also allows you to continue to tweak your program according to the business climate. (Again, be sure to keep track of development costs.) When you reach the end of your measurement term, take your final measurements then analyze the impact the program had on the business, both hard benefits and soft benefits. Was your program successful? Hopefully, the answer is yes and you’re able to see real cost-savings as well as tangible soft benefits.

By viewing ROI as a welcome opportunity to demonstrate your department’s value to the company, you empower yourself (and your employees) to have a bigger impact on the business. Embracing ROI helps eliminate unwarranted fear and replace it with the confidence needed to support the programs you’re passionate about. You also demonstrate that you are committed to being fiscally responsible to your team as well as the business as a whole. With all those benefits, how could you not want to show the Return on Investment for the projects you currently have going?

In a WordPress world, I went with DasBlog. My choice was purely based on language needs – I have a Windows/.NET based website. I needed a blogging platform that seamlessly integrated with it. Enter DasBlog.

My one concern with DasBlog was the limited amount of themes. It was essential that my blog be similar to my Written Designs website and have a professional look-and-feel. On the DasBlog website there are only had handful of themes to choose from. However, the instructions for customizing a theme were readily available. After looking through the themes, I found elements from a couple I liked. Sweet – with these instructions, I’ll be able to create my custom theme in no time!

Well, no time turned into days (a phenomenon many developers are familiar with). While I figured out how to modify the homeTemplate, dayTemplate, and itemTemplate as well as each CSS sheet with ease, I could not figure out how to register my custom theme. The code that the DasBlog site says is in the web.config file is not there. (Grrr!) After doing a few Google searches, I discovered other people had similar issues with customization. “Well, ok,” I thought, “I'll just work around it.”

For the time being I settled with simply overwriting an existing theme to bypass not being able to add my own. The following day, on a whim, I started looking through the code in some of the other theme files. Low and behold, I discovered the problem!

Instead of the registry code being in the web.config file, it is contained within theme.manifest file within each theme folder. While this is noted on the customization page, the explanation is simply that the new version (1.9) now utilizes these new theme manifests. Scrolling down the page, you still find instructions for adding this info to the web.config file. Hmmm, so how does it really work then?

Once you update your specific theme manifest, the code gets referenced from the site.config file. Ta-da you have your theme registered! After thoroughly reading through each page on customizations on the DasBlog site, I found that this information is included, but it takes some looking (you have to read - not skim). So here’s a quick reference to register your new DasBlog theme (for those who are skimmers like me):

1. Copy an existing theme folder down from your ftp server. Or create each file needed for your new theme.
2. Copy the site.config file from your ftp server.
3. Open the theme.manifest file. Update the theme name, title, templatedirectory, and imagedirectory items. Save the file.
4. Open the site.config file. Update the Theme to the theme name indicated in the theme.manifest file. Save the file.
5. Upload your new theme folder and the site.config file back to the live ftp server.

Presto! You’ve got your own DasBlog theme registered and ready to use. Now it’s time to start blogging. Go Write Now!