Archive of Articles about Writing

My Current Technical Writing Toolset

Ten years ago, most of these tools would not have been on my list. Only Microsoft Office, WordPress, Acrobat, and Notepad have remained in my toolset over the past ten years. Some bigger names that have fallen off my list over the past few years include RoboHelp, DreamWeaver, FrameMaker, and PaintShop Pro. That is partially due to personal preferences, and largely due to the company I work for and the job I do for them. I haven’t included browsers here, but the short answer is that I use all the major ones for one thing or another but Chrome is my primary.

Content Tools

Confluence

Confluence is the wiki on which we write and publish most of our documentation at my job. I was part of the team that chose it and launched it at our company. I am also one of the administrators. I have my own cloud version that I use for all of my non-work writing. For the most part, it has replaced word processors as my default when writing. Having it in the cloud means that all of my work, and the interface to develop it with, are available wherever I go and whatever machine I am on.

Microsoft SharePoint

Our company’s intranet sites are developed using SharePoint. I am the SharePoint administrator for the development and support arm of my company. I spend a lot of time curating content and fixing/redesigning pages.

Snagit Editor

I not only use Snagit for screenshots, I do most of my image editing using its editor. It isn’t full-featured like Gimp (my other image editing program) but because it has a simple interface, and some nice out-of the box annotation graphics. I use it for most work-related image creation and editing.

Microsoft PowerPoint

I frequently create presentations, usually just a few slides. I also use it for text-heavy image work because it is easy to move elements around on the page.

ER Studio Data Architect

This is not a common technical writer tool. I support our data dictionaries, which led to me becoming one of two administrators for this tool. I don’t develop data dictionaries from scratch, but I often come in and clean them up for publication. I am the main support person for the tool, so if anyone has trouble publishing their data dictionaries, I come in and troubleshoot the problem.

Adobe Captivate

Every once in a while I need to make a video and this is the program I use. Captivate is actually a little high-end for my purposes, so I end up tripping over some features, but in the end I come out with some nice videos.

Gimp

If Snagit Editor can’t do the job with an image, Gimp is my fallback. It is much more powerful, but far more complex, which slows me down.

Microsoft Word

I rarely write from scratch in Microsoft Word, because I have Confluence, but I still get Word documents from other people that I need to edit. I also use it whenever I need to change the capitalization for a large block of words, or if I want to convert text to a table or a table to text.

Microsoft Excel

We report a lot of information in spreadsheets, and Excel is still the best tool for that.

Notepad

I mainly use this for notes and when I want to remove formatting from a block of text in another program.

WordPress

This isn’t used for my job often, but I still maintain my personal web sites in WordPress. Occasionally, I also use it to do some quick and dirty HTML editing.

TinyLetter

I use this to publish my newsletter. It has a nice, straightforward interface that is almost like sending an email.

Adobe Acrobat Standard

Every once in a while, I need to publish or edit a PDF.

Productivity Tools

Jira

My group at work tracks its projects using Jira. We’ve only been at it for a few months, and I am still getting used to the interface, but it does a good job of making my deliverables clear and letting my boss know when I do and do not have time for additional work.

HP Agile Manager

Another group at work is using HP Agile Manager for tracking a single project that I work on. It does the same thing as Jira, and I like the basic interface a little better, but either tool will do the job.

Trello

Trello is a much simpler project tracking tool that I use for my own projects. It is quick, easy, and surprisingly powerful if you want to dig a little deeper. I can break out project steps very quickly in Trello, which is something I cannot do quickly in Jira or HP Agile manager.

Microsoft Outlook

I could just as easily put this in as a meetings and communication tools, but I put it here because the calendar in Outlook is the first place I go to see what kind of day I am going to have. I use Outlook for email, of course, but the calendar is what keeps me afloat.

Meeting and Communication Tools

GoToMeeting

I run several meetings and attend far more. GoToMeeting allows me to use both audio and screen sharing.

Microsoft Lync

Lync can do many of the same things as GoToMeeting, but is dependent on other people having the program. I use it more for instant messaging with co-workers and occasionally sharing a screen. Some coworkers run meetings using it.

Web Help Tools

I can export HTML from Confluence and use it to build web-help files. These are the tools that help me do it.

Advanced Renamer

I use this to rename large blocks of files. This allows me to get rid of special characters in the names that could be problematic for some browsers.

TextCrawler

I use this to make edits to large blocks of files. Once I change the names of a block of files using Advanced Renamer, I need to change all the links. TextCrawler also allows me to change headers and footers quickly.

Zoom Search Engine Indexer

I can create a search engine for a set of HTML files using this program.

NotePad ++

If I need to edit HTML for a file, I use Notepad++.

Xenu

If I need to check for broken links on a web site, I use Xenu.

Usability: Brainstorming User Issues

Designing a good user interface on a tight budget is not an easy task. One of the things that quickly gets dropped is usability, and especially user testing. Ideally, any new interface should be deigned with input from and testing by potential users. Testing and input not only eliminate minor process issues, it also helps you clarify your whole project.

When there is little or no budget for user testing, there are some steps you can take to increase usability. One of these is to brainstorm about user issues and solutions. Get your design group together, along with anyone you can think of who might represent a user or at least a fresh perspective. Once everyone is together, spend the meeting generating a list of the problems a user might have with your proposed (or existing) product.

Some items to discuss are:

  • Process issues (steps to be taken, input methods)
  • Visualization issues (Look and feel, attractiveness, prioritization of tasks)
  • User goals (What the user gets, what the user is trying to accomplish, what the results are used for)
  • Possible user surprises (Events that a user might not expect or might be confused by)
  • Information / help points (Places where you might need to include extra information or help)
  • Expert / casual / novice user needs (Shortcuts, explanations, toolsets)

One you have a good list of the issues, discuss what you can do to eliminate as many of them as possible. The earlier you are in the planning stage when you address these issues, the less painful it will be to make changes.

Usability: Do you want the data or the conversion?

Over at Usability Counts they ran an article a while back about how Expedia generated $12 million a year in additional income just by eliminating a single, optional field from their form. The field was confusing to customers and resulted in many people abandoning their transaction right at the end of the process, just because Expedia wanted a little extra information and people didn’t know what to put there. Expedia might have looked for ways to make the request clearer, but instead they took the smarter step of just eliminating the field entirely. The extra information was a nice to have, the sale was the goal.

This struck a chord with me because I recently started an email account just for coupons, especially restaurant coupons. I then began going to the sites of all the restaurants I like and joining their email clubs. Thanks to Google, I can fill out most of a form automatically and the process goes quickly. The problem comes when a web site asks for more information than is necessary or expected.

All I want is for the site to email me their coupons so that I can use them for the occasional night out. I believe this is all that most people want when they sign up for a restaurant’s email list. We don’t want them to send us text updates. We don’t want them to call us. We certainly don’t want to register as a user on their site and give them a user name and password that we’ll never remember. Unfortunately, many restaurant web sites want us to do all of these things. It’s a waste of our time, and an abuse of our interest in them. I have to wonder how many potential customers give up when they see these fields.

The key, when you are trying to convert a lead, is to make it as easy as possible for the lead to say yes. That’s why I appreciated one site that simply asked for my name and my email address. That’s all they needed and I was happy to give it to them. A few seconds later, they emailed me a coupon and I used it the next day. That, my friends, is usability.

Turnover, Freedom, and Standards

Turnover

At work this week, we are losing one of my favorite and most relied upon coworkers. He’s a programmer who helped build and customize our customer help delivery site. It is a massive site for a massive set of products. Beyond missing him personally, I will miss his understanding of the giant ball of code that keeps our systems running. If you ever doubt the difficulty of this, spend a little time reading this essay at Still Drinking. Last summer, we lost the other programmer who helped build this platform, and so all of the key builders are gone. We have another programmer who replaced the last, and he is good at his job, but the depth of experience with our little beast of a platform went from vast to minimal in the span of less than a year. That is a problem and it will have clear consequences when it comes to future development. I’m not sure if it was avoidable though.

Freedom

GlassesWhy did we lose these guys? I can only speculate, but I think the freedom to create is a big part of it. When the platform was young, there was much to do. As a small group without a lot of people watching over them, they were able to build it with a certain amount of freedom. Did they create the perfect platform? No, there are issues, but they created something good and useful. As time progressed and the visibility of the project got higher, the number of people who wanted a say in how it was built began to grow. Over the past couple years, there have been a lot of people who wanted a say in how this (now high profile) platform moves forward. The programmers were no longer creating in a vacuum. People were watching what they did and for better or worse, telling them what was wrong (real or perceived) with the platform that they built. The freedom to create was gone.

I’ve left a few jobs in my time (sometimes by choice, sometimes not) and one of the overwhelming feelings I’ve gotten every time, is one of freedom. Sure, leaving a job is scary, but when a job ends, so does a wall of rules that have kept you constricted. For a creative person, and most good programmers are endlessly creative, freedom is a necessary tool. I’m not criticizing usability studies, standards, and design oversight. They are an important component of a development project. Nonetheless, there has to be a balance. There are programmers out there who care only about the code. Give them a clear design with a set goal and they can do it. For most though, that much limitation starts to kill their passion for what they do. The desire to be free to create becomes overwhelming. In many cases, people just end up swapping one set of restrictions for another set at a new company, but even that can be better. At least the restrictions were there when you got there, rather than imposed along the way.

Standards

It is the same for writers as for programmers. At my job, I am the leader of the technical communications standards committee (I named us the Standards Heroes). We discuss and vote on everything from broad concepts to nit-picky word choices for our technical communications strategy. Some people might think I am a strange choice for this. I am not a member of the grammar police, as anyone who reads this site knows. In a way though, it is why I belong at the top of that standards heap. I don’t want to overburden us with rules. I want there to be a certain amount of freedom to create, even in a technical atmosphere. I understand that there are some writers, like some programmers, who only want to know exactly what to do and exactly how to do it, but I want to leave room for creative people who just want a path to guide them, not walls to limit them.

What do you think? What is the best balance between rules, standards, oversight, and the freedom to be creative?

What I’m Reading

Rachel Rachelle Gardner over at Books and Such has a nice article about How to Work With a Freelance Editor.

Some good advice:

  • Use it as a learning experience.
  • Make the changes yourself.
  • Start with an evaluation of the first few chapters.

Janice Hardy over at Fiction University discusses Balancing the Number of Characters and the Scale of Your World.

She talks about social hierarchies and bonds between social groups, using a school classroom as an analogy. She also shows some of the ways you can demonstrate the size of a community even without having a flood of characters.

Leslie Jordan Clary over at Make a Living Writing writes about How I Found a Steady Stream of Writing Clients in 9 Months Flat

I agree with her advice about developing a niche. I think it is important to have a writing focus that people can know you for. I make my living as a technical writer with a web development background. I’ve never made much of a living writing general articles, even though I have done so on occasion because I enjoy it. I’m not a true freelancer though; I mainly worked on contract and now have a “permanent” gig. Your mileage may vary.

Deb Ng over at Kommein lets people know that Freelancing Doesn’t Look Like This.

She critiques an advertisement for “freelance writing riches” that shows a woman sitting on a rocky beach, typing on a laptop. Beyond that fact that nobody sits for long on a pile of rocks expecting to get work done, she makes the point that a freelancer’s hours are long, clients often don’t pay on time, and people never really think of what you’re doing as a “real job”. I’ve had a couple of deadbeat clients in my time. It is very frustrating. I don’t miss it. As for typing on the beach, I would if I could but I’d prefer bigger, flatter rocks.