Tips for hiring an outsourced technical writing team to document your product or process

30
Mar0

Consider the following factors before selecting an outsourced technical writing team to develop and/or maintain your technical or product documentation. Carefully selecting the right team of writers can make a difference in the success of a product launch as well as influence whether or not your product is successful in the marketplace. Keep in mind that technical writing teams are not one-size-fits-all organizations, so it’s up to you to take the time to find the right fit for your needs and organization.

Return to Your Writing Dept

Define why you need documentation
You first need to clearly establish why you need documentation for your product or procedure. Is it new documentation to support a newly developed product or do you need to improve existing documentation to further assist in customer support? Fully determine why you need to engage a technical documentation service provider before starting a writing project.

Engage the writing team early in the process
Many technical writers are all too familiar with being brought in late in the game of product development only to join in on the mad dash to the product delivery launch date. Bringing the writing team in early allows for better documentation and a better customer experience.

Establish your budget
Set realistic limits as to what you are going to spend on your documentation project, but understand that the final user guide is designed to support your product and if it falls short of your customer’s expectations, your product may not be well-received. So plan early for your documentation requirements and factor your ROI in the cost of the documentation. Planning to go on the cheap will usually get you into trouble. In budgeting, you need to consider if you want to build document templates and style guides as a part of the project. An experienced writing team will build in time for documentation review cycles. Generally, when scoping a writing project, a technical documentation outsourcing team will look at the estimated number of pages and calculate the time to complete the project, so it is important to represent your project as accurately as you can. Neither party wants to be surprised by price over runs because a project was scoped inaccurately.

Assign the internal support resources to the project
Writers from the outside your organization may be good writers, but they may not know your product the way you do, so set aside the time for your subject matter experts to participate in the documentation development process in an advisory role. Clearly define roles and responsibilities and get buy in from the subject matter experts.

Establish if you need a local writing resource
Consider if it is important to the success of the project to have a writer is on-site. Determine if the writer will need to have face-to-face meetings with your subject matter experts, or can they be on the other site of the country? For documenting some products and processes, location is not important.

Decide if you will require project management services
Determine if you want a formalized project management process or if the project does not warrant close supervision to keep the project on track. When developing a complex or large document suite, a project manager can help keep the project on track and free up the writer’s time for the actual writing. Although project management is an extra cost, it can keep the project moving in the right direction and keep it within budgetary restraints. Keep in mind that adding project management time into the estimate will generally include several hours per week to accommodate the project manager’s time above the technical writing efforts.

Your Writing Dept is a Sacramento-based writing firm that specializes in developing technical manuals and user guides. We like to say that we can be your tech writing team, without the overhead. Email us for more information about our services at info@yourwritingdept.com.

Additional Posts from Your Writing Dept

Filed under: The Writing Life, Tips
No Comments

InfoPorn: Presenting raw data with visually stimulating graphs

24
Mar0

When you have raw data to present in a document, you can do one of two things. Hide the information in a table and make the reader dig through it to find something useful, or you can create a visually interesting graph to draw the reader in to become a part of the data. Making useless data interesting and frighteningly captivating is what we like to call “InfoPorn.”We’re the leaders in technical communications in Northern California.

So what can you do with compelling graphs, you ask? You can explain complex flows of money such as the recent AIG bailout. Follow the money, as they say. In this case, where did the $173 billion go during a six-month period?

If you have bad news to deliver through a visual presentation, there are ways to soften or re-direct the data to make the bad news not quite so bad. Take Four Different Looks at Job Losses During Recessions for example. Wait, is this good news or bad news? You decide.

Wired Magazine devotes a double-page spread in each issue to present what would be overwhelmingly dull quantitative information in an interesting presentation. Yes, they are turning a bunch of raw numbers into visually stimulating infoporn. A recent presentation explores something you may have never considered: Playboy Playmate BMI and Average BMI, 1954-2008. Wired Magazine might be taking the presentation of information past what the average Excel user can do with even the most advanced graph functions, but with some imagination, Excel can be used to create some killer graphs.

Junk Charts has a good collection of visualizations and good critiques as to whether the charts present data accurately or serve to skew data for the benefit of the presenter.

One of our greatest sources for inspiration on how to present data has come from Edward Tufte. Through his books, papers and one-day courses, Tufte takes us through the history, uses and misuses of presenting quantitative information. Anyone who has attended one of his courses either drinks the Kool-Aid or not, but one has to admit that his books are a step above the average coffee table book.

So the next time you have to build a graph using Microsoft Excel, try to think outside the box and go beyond their default graph designs. Be daring. Be different. Create yourself some infoporn. Go ahead, we know you want to.

Your Writing Dept is a Sacramento-based writing firm that specializes in developing technical manuals and user guides. We’re the leaders in technical communications in Northern California. Email us for more information about our services at info@yourwritingdept.com.

Additional Posts from Your Writing Dept

Filed under: Writing Tips
No Comments

Newspapers are dying but there’s still a need for good journalism

18
Mar1

I’m frustrated that many writers are heralding the death of journalism when in truth, the newspaper industry is taking the hit. Reporting, journalism and good old fashion getting the word out are all here to stay.

The fact is that newspapers as we have known them are dying, so as readers and consumers of news, we need to accept this fact and move on to other means for consuming the news. And if you truly look at how a newspaper is run as a business these days, the daily paper no longer fills our needs as a culture anyway. It’s too slow, it will never be a green industry and it’s losing its ability to complete with online delivery.

But as the medium shifts from the paper and ink newspaper with it’s traditional newsroom checks and balances, we should demand that good reporting techniques and practices be important in the development of the new and emerging mediums such as blogs, Twitter posts and other online venues.

Traditional newspapers are competing with the Internet and free content, of course, and recent news of the 146-year-old Seattle Post-Intelligencer going to web-only delivery should be an indicator that more of the larger papers will be taking this route to stay in business.

Newspapers that do survive will also face more competition with citizen journalists who, with a simple blog, cell phone, and Twitter account, can get breaking news to readers faster than the printers can ink the plates and roll the presses. Gone are the days when only reporters and establish news agencies break and subsequently publish the news.

So it’s becoming more important for their overall survival that newspapers adapt to new technologies and also break news through Twitter and their online sites. A must read on the subject of newspapers getting into social media can be found in Woody Lewis’ 10 Ways Newspapers are Using Social Media to Save the Industry.

The word “newspaper” will take on a different meaning, like “record album,” or “TV show.” It won’t go away, and it will continue to describe some of the most hallowed brand names in the world. Social media will play a big part in that transformation. As the dynamics of our society change, as institutions go public or private, or disappear entirely, the need to report these events in a responsible manner will be even more critical. Social journalism is more than a buzzword, it’s the way social media will save the industry.

Another must read is Clay Shirky’s Newspapers and Thinking the Unthinkable.

Society doesn’t need newspapers. What we need is journalism. For a century, the imperatives to strengthen journalism and to strengthen newspapers have been so tightly wound as to be indistinguishable. That’s been a fine accident to have, but when that accident stops, as it is stopping before our eyes, we’re going to need lots of other ways to strengthen journalism instead.

I make the argument that newspaper are not exactly dying, but rather, evolving with the times and the current needs of readers. Those papers that find ways to evolve effectively, will survive, and those that do not, will perish. Hey, it’s all about adapting to new business climates and finding new opportunities.

A few good sites for more information about the future of newspapers and journalism

Teaching good reporting skills

‘NYT’ Digital Czar: News Cooperative’s a Possibility

The future of journalism

The importance of The Fourth Estate in democracy

Twitters worth following

@10000Words
@themediaisdying
@journalistics

Your Writing Dept is a Sacramento-based writing firm that specializes in developing technical manuals and user guides. We like to say that we can be your tech writing team, without the overhead. Email us for more information about our services at info@yourwritingdept.com.

Additional Posts from Your Writing Dept

Filed under: The Writing Life
1 Comment

How many spaces after a period? One or two?

2
Mar9

RonBy Ron Creel

The question of how many spaces one should place after a period when typing is a question as hotly debated as whether a roll of toilet paper should unroll from the front or the back.

Let me begin by saying that my mother was a college-level typing instructor back in the day when the use of business machines was taught in community colleges to those who were destined to work in office steno and typing pools. So I grew up learning the finer skills of how to properly load a typewriter with two sheets of paper, including carbon paper if a copy was to be made, and the proper typing techniques. But, oh, how I have rebelled after all these years.

As an editor of other writer’s work, I have seen both single and double space after the period, but for the life of me, I can’t figure out if it’s a matter of education, age, gender, geography or just not really caring one way or another. But it does pretty much cuts down the line.

My own background was to go with the double space or suffer the wrath of my mother, but then going through journalism school in the 1970s, I was taught the single space standard. There’s nothing like a journalism professor and then a hard-drinking, cigar-smoking, cursing newsroom copy editor screaming at you every time you did something wrong to get you with the program. So the single space stuck.Join us on Facebook

So enough of the personal background. So what’s the (modern) reasoning for using the single space, you ask?

It basically comes down to progressing from typewriter-produced monospaced font to computers, which use word processing programs that can handle and adjust the spacing between the period and the beginning of the next sentence.

As for established styles, Modern Language Association (MLA) goes with the single space as a preference, but leaves the door open to say that there is nothing wrong with using two spaces after ending punctuation marks unless an instructor or editor states a preference one way or another. In this case, it’s best to consider the directions of the person assigning the grade or signing the paycheck.

Wikipedia even chimes in with a little information:

The two spaces convention was brought out by the use of monospaced font on typewriters, and carried on solely by tradition. Most fonts used in word processors since the mid-1990’s have the correct spacing already adjusted, rendering the traditional double space after a full stop (period) obsolete.

And there was a LinkedIn discussion posted last year about the topic. Oh, as I said, everyone has an opinion, and this was no exception.

So this is where I stand. If it’s a document I will be managing and someone else has created the document using two spaces, I will change it. However, if I’m editing someone else’s document that I will not manage, I won’t touch the spaces and won’t even mention it. And back in the day when I was grading high school papers, I focused on content, grammar and mechanics. My students really didn’t need to worry about the spacing issue.

My preference? I like one space after the period sort of like the way I prefer the roll of toilet paper to unroll from the back.

Also from Your Writing Dept

Filed under: Just for fun, Writing Tips
9 Comments

Is there an error message for user manual failure?

1
Mar1

I hate my oven. No wait, I hate the Use & Care Guide that came with the oven. I use the oven, a KitchenAid Model KEMC378, quite a bit and it has occasionally shut down and spit out an error message on the front panel. This forces me to dig the manual out of the draw where we keep Chinese restaurant takeout menus, note pads and operator manuals for the large appliances in the kitchen that usually keep our lives moving smoothly.

Well, this is what happened last week. I’m finished baking a wonderful dinner, and as I’m shutting the oven off, the panel flashes an image I’ve never seen…the probe temperature sensor. Hey don’t get me wrong, I’m sure a temperature sensor has its place, but I’m pretty basic when it comes to cooking. My rule is that you set the temperature, put the food item in for about the prescribed time and take it out just before you smell smoke.

So, back to the panel issue. After the probe image stops flashing at me, an error message appears and everything else goes blank. And no amount of  button pressing, kicking and swearing seems to help.

So out comes the manual. I thumb to the back, because from past experience, I know that’s where I will find the troubleshooting section. But wait, there isn’t an all-inclusive error code list. There’s only a reference to a code that will appear if a power failure has occurred. So, it’s off to the Internet to find the code. This is where things appeared to be getting much better for me. I found several long lists of codes that I printed off and stapled to the inside of the manual for future reference, but here’s the rub, the elusive F4 E0 was not listed. What? They had four-digit codes and two-digit codes listed, but my four-digit code wasn’t listed. Oh, what to do? So I called the KitchenAid Customer Interaction Center. Of course, I didn’t really think they were going to be able to help me, but at this point, I just wanted talk with someone.

After getting someone on the line and describing the problem, all the operator could do was repeatedly ask if I had the extended service plan, because if I did, they could have a service technician out in a couple of days to look at it…without charge. Otherwise, I would have to call another company to come out, and they would charge me. Interestingly, she didn’t want to take no for an answer and couldn’t understand why I didn’t have the extended service plan. No, I insisted because number one, I’m cheap, and number two, I thought I was buying a product that might not break.

So after the call didn’t get me what I wanted, I decided to return to the code list and see if I could break down the basic elements of the codes and take matters into my own hands. Since this four-digit code could be broken down as two, separate two-digit codes, relating to electrical shorts in sensors, I thought I could add the flashing image of the temperature probe into the mix and point myself to the problem.

My thought was that something must have gotten into the opening (temperature probe jack) for the sensor probe, which is open and exposed to the heat and smoke produced in the oven. So I shut off the electrical breaker that leads to the oven and gently poked the tip of an ice pick into the opening and twirled it around a bit. And after turning the power back on, I was very pleased to see that the error code was gone and the oven was operating normally.

So here’s what I learned about developing manuals from this little experience:

  • Include every possible error message
  • Provide every possible solution to the error messages so the user can either attempt a fix themselves or make a service call
  • Be honest about whether the user may be able to fix the problem. If they may be able to jiggle this or jiggle that to fix the problem, feel free to mention it.
  • By not providing all possible error messages, you are doing your readers a disservice and might be forcing them to call customer service, who might also be less than helpful
  • When developing a product, let your writers have hands-on time with the product to verify how the user will see the product and the manuals together. Don’t just make them rely on engineering notes.

After all this, I still like my oven, but I now have a better appreciation for the need to list error messages and associated solutions to make manuals more useful. And now, would anyone care for some warm blueberries muffins?

Your Writing Dept is a Sacramento-based writing firm that specializes in developing technical manuals and user guides. We like to say that we can be your tech writing team, without the overhead. Email us for more information about our services at info@yourwritingdept.com.

Additional Posts from Your Writing Dept

Filed under: Writing Tips
1 Comment

About us...

Blogroll

Categories

Recent posts

RSS Your Writing Dept Twitter

Archives

Other