Apr 12
20
A word about backing up…
So earlier this week, I was working in a document using my primary software (Adobe FrameMaker) and was working in a table. There was a column of part numbers in this technical manual and each part number in the column had an extra space in front of it. Simple enough – you just select the column, do a “find and replace” on the space, replacing it with nothing. Voila, the spaced disappear.
FrameMaker has this wonderful extended “find and replace” function that allows you to replace things in one of three ways. You can replace all occurrences in the text that is currently selected, OR you can replace all occurrences in the open document OR you can replace all occurrences in the book (typically, there are multiple files in a book. This particular book has 21 files in it.
As you may have guessed by now, I had the wrong option selected. I hit “Replace All” and watched as FrameMaker dutifully deleted EVERY SPACE IN THE BOOK. All 21 files.
Now you can see how important it is to have current backups. It might have taken me a week to go through and repair the damage done to this book if I had not had a good backup. I use something called Mozy (http://www.mozy.com). Mozy works in the background and it actually backs up files as they are changed to The Cloud. You can manipulate the settings, but in simple terms, my working files get backed up a minimum of four times a day. In addition to this, I have another software (SyncBack SE) that does an nightly backup to another computer here in the office.
I’ve had to restore the occasional file from Mozy over the past couple of years, but this is the first time it’s REALLY saved my bacon. I was able to go to Mozy, do a quick restore of the files, and within about 15 minutes I was back where I’d started.
Don’t take this as a commercial for Mozy (I’m not being compensated for this testimonial), but if you’re not backing up your files in a regular, automated, systematic fashion, you are asking for trouble.
May 11
24
Real Life Intervenes
For some time now, our employees have mostly telecommuted. There are advantages and disadvantages of this, but it has worked out really well. Commuting from the bedroom to the desk in your pajamas is pretty nice.
One of our employees has recently started a relocation. He was supposed to travel to Joplin, Missouri this week to begin shopping for a house there.
Joplin, Missouri
I’m glad he wasn’t already in town. My heart goes out to the people of Joplin. Living in Tornado Alley, you always have this threat in mind when a storm blows in. I was living near Lubbock in 1970 when a tornado tore through this city and killed 23. I vividly remember driving through town a few days after the storm and seeing the incredible destruction. As dreadfully awful as that was, the destruction of the Joplin storm dwarfs what happened in Lubbock.
If you haven’t I encourage you to visit the American Red Cross website and make a donation. Small contributions help.
Mar 11
8
Technical Writing Specifications
By its very nature, technical writing is structured and concise. To ensure that technical manuals are consistent, many projects are required to comply with existing specifications. For example, the military has a number of specifications that define the content and format of their manuals. In addition there are many industry-specific specifications.
The primary military specification for technical manuals is MIL-STD-38784. This document describes in detail every aspect of a technical manual, including formatting, layout, content, and many other practices. There are illustrations in the appendix to show you exactly how, for example, a U.S Army technical manual should appear. But even with this level of detail, it has been my experience that every acquiring command will have different ideas on how they want their manual to look.
ATA 100 is the corresponding specification for the Air Transport Association. This specification has individual chapters describing how to document, for example the electrical system, the communication system, or the auxiliary power system.
To comply with these specifications, you must also make sure your artwork is correctly created. Military manuals must have line art illustrations; photos are prohibited. Other specifications have similar restrictions.
Writing software documentation presents different challenges. The old Digital Equipment Corporation produced an excellent guide for software technical writing called the Digital Style Guide. Another excellent book for software technical writers is the Microsoft Manual of Style. This guide does a great job of describing the elements of a software user interface. It will tell you how to refer to radio buttons, checkboxes, and spinner controls in your program.
When you are working in certain industries or with smaller customers, there may not be any clear specification to follow. I would recommend that you examine the publications of other companies in the same line of business (suppliers and vendors) to see what their technical manuals look like. Or you can adapt one of the aforementioned specifications to the task, even though they may be overkill for smaller projects.
To continue yesterday’s post, I was lamenting the fact that being a Technical Writer causes me to feel guilty whenever something around the house breaks and I can’t fix it. As many repair procedures as I’ve written, I should be able to handle anything.
My greatest triumph in the arena of home repairs came about two years ago. We have a nice Samsung 46-inch LCD high-definition television. For a few weeks, whenever you would turn the set on, it would click a couple of times, as if it were trying to power up, before it finally came on. As each day passed, the clicks lasted longer and it took four or five seconds for the TV to come on.
This trend was troubling, and sure enough I came home for lunch one Friday and the clicking had given way to a complete failure. The TV would not power up at all.
The prospect of a weekend without television spurred me to immediate action. I got online and searched for Samsung TV issues. It didn’t take long to discover that there were a LOT of Samsung sets that had this problem. The root cause could be found in four capacitors on the main power board assembly. Apparently Samsung got a load of bad components and they were failing prematurely.
There were three avenues to pursue:
- Call a repairman. Likely course of action would be to replace the entire main power assembly for a cost of $500.00 or more. (pshh… yeah, right!)
- Replace the entire main power assembly. These could be found on eBay for around $200.00 (hmmm… now that may be doable…)
- Remove the main power assembly and replace the defective capacitors. (Now we’re talking!)
As I mentioned in my previous post, one of the keys to being able to repair something (aside from having excellent technical manuals!) is being able to procure suitable replacement parts. This was the first challenge. I needed four capacitors – as I remember it was two 2200 µF caps and two 1000 µF caps. Radio Shack was the first, logical place to look. Well, back in the olden days you would have had no problem finding these components at Radio Shack, but not any more. So I went to the local Fry’s Electronics in Dallas. They had one 2200 µF cap. Drat.
Another internet search revealed an electronics shop in Carrollton. A quick 40-minute drive up there and I had the parts I needed. Total cost: under $8.00. I did have to buy a new soldering iron and some solder too, so I probably spent another $15.00 or so.
Armed with my parts and tools, I got to work. My soldering skills were *ahem* a little rusty, so this part took a lot longer than I expected. But soon enough I had the capacitors wedged into place. The new caps were significantly larger than the previous ones, so the repair job looked a little weird, but the specs on the caps were plenty robust enough that I felt good about my work.
It took a good 30 minutes to reassemble the TV and get ready for the moment of truth. Honestly, I could feel my pulse quicken a little bit as I held the remote in my hand and got ready to click the power button.
Here we go….. *click*
YES!!
Oh, crap.
The TV came on instantly and my emotions soared. Sadly, my victory was short-lived. Within about 3 seconds I heard a muted “pop” sound, the picture disappeared, and a cloud of pure white smoke came pouring out of the TV.
Well, that can’t be good.
The autopsy revealed that I had committed a very rookie mistake. Capacitors have a polarity, like a battery, so you have to install them with the + side and the – side oriented correctly. Another 40 minute drive back to the electronics store, another hour or so to de-solder the bad capacitor, replace it with a PROPERLY oriented new one, and I was back at the starting line again.
I can proudly say that today, two years later we’re still watching the same TV and it works as good as new. I have learned that Samsung is now offering a free repair on models affected by the bad caps. Too late for me, but I now have a very solid “skin on the wall” when it comes to home repair. The Technical Writer has conquered the television.
I continue to be tormented by the icemaker, but that’s another story.
Every job has its drawbacks. I’m sure even Warren Buffett could tell you some things about his daily work that are less than desirable, although having a bank balance with 10 digits and three commas would tend to make things better.
As a technical writer, I have written procedures detailing how to repair all sorts of equipment-both military and commercial. I have described the overhaul of diesel engines. I have written detailed troubleshooting procedures for night vision equipment. I have developed repair procedures for HVAC systems, computers, optics, hydraulic jacks, and all sorts of other equipment.
So when something in my house fails, I feel like I should be able to repair it. It just seems logical, right?
Well, one section that goes into almost every technical manual that we write here at Allard is a table listing the necessary tools and equipment to accomplish the repair procedures. I have a lot of tools, but it seems like every project that comes along will require at least one trip to Home Depot.
Another prerequisite for repairing things is the ability to acquire a suitable replacement part. That’s often easier said than done. I have spent a lot of time searching eBay for some random part to repair something in the house. For example, my in-laws complained that the racks inside their dishwasher had basically rusted to the point they were disintegrating. I figured this would be something really easy to fix. I mean, there aren’t any tools involved, and the replacement parts should be really easy to find. At least you would think so.
After writing down the model number for their dishwasher (which was not really all that old), I headed to eBay confident that I would be able to find a perfect replacement at a very reasonable cost. It turns out dishwasher racks are a very complicated thing. I did actually locate a seller on eBay that had the racks needed. But the prices commanded for these things were nothing short of shocking. Suffice to say, it would be cheaper to trip out to Sears or Home Depot and buy a new dishwasher.
But once in a great while, you find yourself with the right tools and the right replacement parts, and things fall into place as they should. The Technical Writer will surely triumph this time. Probably my greatest achievement in home appliance repair involved one of my most prized possessions – my 46-inch Samsung HD television. While it wasn’t pretty, I did manage to get it fixed and it still works fine to this day, but the battle was tough and casualties were incurred.
I’ll fill you in on the gory details in my next post.