Will Kelly

Thoughts about Technical Editing and Reviewing

I would be the first person to describe myself as a blank pages kind of a technical writer  because I like writing documents from scratch and see it as one of my strengths (or at least I like to think so).

However, some current and recent projects have placed me more into a reviewer and editor role and has got me thinking about technical editing and reviewing including:

Five Things Technical Writers need to do at least Once

I've had a chance to meet with some technical writers, hiring managers, and potential clients over the past few weeks and the picture of the technical writing profession remains as troubled as ever.

While many senior technical writers are driven into contracting there is still an insular technical writing community that has never taken such risks. Personally, I think every technical writer needs to spend some time as a W2 and independent contractor and publish original work to expand their own horizons beyond just font fondling.

Writing Samples for Technical Writers

My latest round of interviews and potential client meetings are causing me to reflect about writing samples and their use in the interview process.

At least in my experience, what passes for quality technical writing can vary slightly if not significantly from one organization to another. This means that an A+ document in one organization may not cut it in another organization.

Things your Technical Writer or Requirements Analyst isn't Telling You

Executives, programmers, and engineers may think they are exclusive castes but there are many tell signs that technical writers, and requirements analysts know.

1. You don't know as much about our technology as you portray. This is not a bad thing. However, you make it suck because you aren't willing to sit down with the people who know and educate yourself about technology. Your underlings are willing to help if you would only ask. You can't hide forever.
2. Your emotional blustering and posturing only serves to degrade your credibility.
3. You are phoning it in and have been doing it for sometime.
4. You lack problem solving and analytical skills.

Leaving Technical Writing

It's time to turn out the lights. I've had a great run as a technical writer and consultant but it's time to leave the profession. In some ways I've long outgrown technical writing because client needs as a consultant challenged me and pushed me to become more than just a technical writer.

Kelly's Laws of Wiki Implementation

Wikis should be a force for good. Unfortunately, my experience on client sites where they've implemented  wikis has always been very black and white. The user community is either craving a wiki or they find it too disorganized and difficult to use.

The Technical Writer's Five Best Friends

Technical writers need expand their personal and professional friends as building a technically strong personal and professional network

The Product Manager: The product manager can be the technical writer's best friend or worst enemy but knowing and relating to experienced and competent product managers can aid technical writers to better understand the product they are documenting. On the dark side, when faced with incompetent product management, a technical writer with their grounding in writing product requirements and functional specifications can help be a voice of reason during the triage of ambiguous or just plain technically unfeasible requirements.

The Senior DBA/Database Architect: The whole world and many of today's leading edge Web applications run on databases making a senior DBA and database architect a valuable friend indeed.

The Storage Area Network Engineer: All the business world's data (and secrets) reside on one SAN or another and understanding enterprise storage can only help a technical writer.

The Financial Controller: It never hurts to know the person who handles the money and processes the checks. This is doubly true for freelancers and independent contractors.

The Architect: Software architects and Network architects are another valuable friend of the technical writer because of their responsibilities sway over the design of software and systems.

Indelible Truthes Learned from IT Contracting & Consulting

Working as an IT consultant and contractor can teach a lot of life lessons and illuminate a lot of truths into human nature. I've seen a lot working with commercial, Federal, non-profit, and non-governmental organizations.

Here are some of the truths I've learned over time:

Reason #3245 to despise Hummingbird DM

It's so poorly designed that it's obvious Hummingbird DM was designed to stoke professional services revenues for Hummingbird.

Lucky #13 or “Why Johnny Can’t Write Technical Documentation”

I’ve started this post a couple of time but hit delete. While the STC is up in a lather over technical writer making #13 on Consumer Reports  Money Advisor best jobs list, I am still so confused over how technical writer made the list in the first place.

My criticism about the technical writer profession can easily be found searching this site. However, I’ve also written articles on the issues surrounding the hiring of technical writers and outsourcing of technical documentation.

How can technical writer make the list in a world where:

1. Senior technical writers are often exiled out to the contractor iceberg when they want to earn a living wage.
2. Everybody has had a bad experience with technical writers or so the joke goes.
   
3. Technical staff flashback to freshman comp 101 and other mandatory English classes meaning documentation is relegated to the backburner.
   
4. Hiring managers have a hard time qualifying their technical documentation needs.
   
5. Too many organizations are confused about the true potential and role of a technical writer and the role of the technical writer falls into the administrative assistant/receptionist/barista/copy editor/bottle washer/desktop publisher black hole.
   
6. Technical writing is a young person's profession by and large because it is often classed as a support function meaning there  are corners to be cut.
7. End customers have low expectations about technical documentation meaning they may never RTFM.
   

Kelly's Law of using Software Applications

The software application works for you. You don't work for the application.

Spending another week wrestling with some Microsoft/Hummingbird DM issues brought this home again.

Ways a Technical Writer can lose an argument

While technical writers often lament that they often lose workplace arguments it is often their own fault in how they position themselves within their organization.

Setting your Project Documentation up to Fail

While the current sorry state of the technical writer profession should carry much of the blame about project documentation failures, hiring managers aren't without sin in the matter.

Hiring managers are within their full rights to roll their own kind of technical writer. Most managers don't want to worry about their project documentation though they pour such little foresight into the potential success of the activity.

How ambiguity killed the technical writer

Too many technical writers live ensconced in style guides, single sourcing, FrameMaker, processes, and methodologies away from the business of developing software. This monk like college advanced composition teacher existence can separate the technical writer from the realities of today’s dysfunctional workplace.

Reasons why a technical writer can't be a user advocate

Many technical writers will tout their role as a user advocate. Here are some reasons why as a technical writer you can't be a user advocate:

1. You've never left your cubicle.
2. You've never read any professional publications or Websites related to the user community for the product you are documenting.
3. You've never had an indepth discussion about product features and client needs with a product manager or sales person over the product.
4. Your only encounter with the product is information emailed to you from the development team.
5. You've only taken meeting minutes at development team meetings and neglected to participate in a substantive way with the group.
6. You've never used the product to conduct ordinary business tasks in accordance with use cases or your own proclivities.
7. You've never met a living, breathing, paying user of your employer's product.
8. Your lack of computer experience isn't directly relevant to the user interface of your employer's product.
9. You never asked for access to your organization's bug tracking system.
10. You've never written a ticket about a UI (User Interface) issue and submitted it to your organization's bug tracking system.

Why your coworkers think you are a technical writer with a stick up your a**

Recently, I was talking with some of the other contractors I share office space with and the conversation spilled over to some of their perceptions of technical writers. They thought I broke the mold, and wanted to share their experience with me.

I got some interesting insights into why people have a disdain for technical writers. Some reasons why people think technical writers have a stick up their a** came up in the conversation including:

1. You have no sense of humor.
2. You correct the grammar of team members when they are speaking to you or  each other informally.
3. You lead with the broad technical question first without trying to make the attempt to answer questions yourself.
4. Google? Yahoo? You just ask one of my SMEs!
5. You worship FrameMaker as a religion and try to work the product into many of your conversations with non-technical writers. Newsflash, they could care less about the intricacies of FrameMaker.
6. You admit openly to not really being into this technology thing.
7. You forgot to leave your teacher voice back in the school classroom where it belongs.
8. You fell for the meeting minutes trap and agree to take minutes in staff meetings. Now the programmers, engineers, and project managers can only confuse you with a secretary. Staying mum to capture meeting minutes only digs your hole deeper.
9. You have let classic literature, grammar, syntax, show tunes, NPR, and a suburban garden apartment full of cats shape your personality.
10. You think chocolate and food will grease the wheels to get you information from the development team. What about off color email jokes, porn site URLS, and beers after work? A brownie is only going to get you so far depending on the audience.

Going in through the side door

Technical writers and trainers often feel they are ignored during the development and deployment process. Whose fault is it that they are the last to know big news? While cultural issues come into play, technical writers and trainers need to look at going through the side door for technical information and other needs during the course of the project rather than having it served up to them by the project team.

Vesting in the project’s technologies is the first step to the side door for project information and other needs. Often times nothing is stopping documentation and training groups can use their own devices to get a access to software and/or hardware for their projects except their own inaction. Another big change is that they have to put some intellectual equity into learning the new technologies on their own.

When Swept Along Technical Writers Attack!!

In some cases to protect their fortress of ineptitude, a swept along technical writer or swept along trainer can show a much darker side. Well, ok if you can suspend disbelief for a moment and believe their hydrogen dirigible view they have of themselves you could call it a darker side.

Very rarely does a manager smoke out the truth behind a swept along technical writer and a swept along trainer, their equally dangerous and inept cousin because technical documentation and/or training is just a line item on a status report.

Typically, it’s one of the staff members who see that the emperor (swept along technical writer) is naked, and not well endowed to boot.

Next when their false pleasantries, long rambling emails, frequent invitations for a same sex walks outside during lunch, and near constant reminders of their Master’s degree don't work they could salivate and want to go on the attack.

What's gone wrong with the Technical Writer profession?

While doing some research for an upcoming article, I had cause to ponder on what I see that has gone wrong with my current profession:

Zen and the Art of Technical Accuracy

Technical accuracy isn't open to debate and is at the heart of solid technical documentation.