It was a busy night. We tend to follow specific shows that, unfortunately, all end up being on Thursday.
1) Survivor (Survivor: Tocantins - The Brazilian Highlands was produced in 2008 and will premiere on February 12, 2009. We have a Survivor pool @ work and I have Debra Beebee, 46, Middle School Principal. I hope she wins so I win the pot.)
2) ER (9-10)
3) the Grey's Anatomy/Private Practice cross-over event (8-10)
4) TNA wrestling ... (8-10)
It started out as a busy day on Techwr-L as well. List member David Downing asked whether software documenters should learn to read code. He wrote that:
One reason programmers tend to make bad documenters is that they think in terms of the mechanics of the program, rather than in terms of the tasks the end user needs to perform. [A] technical writer who starts reading code might start thinking this way as well.
This is my take on it. I am cruising online and I find a CD review of Metallica's "Death Magnetic" CD. As I read it, I can't help but notice that the reviewer has a mastery of the band's material. I read explanations that describe how track such and such is very similar to track such and such on their previous release. I read about chord progressions in track "This" being similar to track "That" on their second release. By reading the review, I -trust- the reviewer's opinion because they are able to explain, in-depth, how the current CD is either better, the same, or worse, than previous releases. The writer is able to pick the important details and eliminate the fluff or irrelevant aspects of the release. They tie the review in a neatly wrapped present. It is easy to read & tells you everything you need to know about the release in order to decide whether or not to purchase it.
Now, apply that to tech writing. I'm reading online Help and read a paragraph that talks about a "Processing" option. The explanation goes into the depths of what is processed, what files are processed, how the files are changed, where you will see evidence that the process updated something, etc.
In the first example, did the reviewer have access to the Metallica release as it was being recorded or to the early demos - the source code? Probably not. They were able to write meaningful prose by fully understanding where the release fit into the big picture.
The same is true in software doc. I do not believe you must have access to the source code in order to fully understand the software. I need to understand what the software does and how it does it, but do I have to read the source code to learn that? Not if I have access to the programmers and SMEs who wrote the source code or designed the source code.
Reading source code would be one tool in your toolbox for writing meaningful doc. This is a touchy subject for me. My mentor @ job #1 was very set in her ways that tech writers did not belong in the source code any more than programmers belonged in doc "source code" files. If there was a question about how something worked, you should ask the programmer. One day, I was instructed to ask the programmer for the valid values for a field. I went to the programmer to ask him. He showed me how to go into the source code - in display mode - and what to search for in order to find the info I needed to write my doc. My mentor's face turned red when she saw what I was doing. "You do not want to be responsible for messing up their code!" she told me. I didn't tell her that I was in display mode - that I couldn't update anything - but I don't think that would have mattered to her.
The problem with asking the programmer, though, is that sometimes the programmer knows what they are doing and sometimes they are just doing what they are told to do so your mileage may vary. Yesterday, I was creating the UI for a new menu option that generates a report that is sent to a 3rd party. I saw the 3rd party referred to as both "APPLES" and "Apples" so I asked how that company should be referred to on the menu option. I asked the programmer who had added the menu option. She said, "I don't know. I've seen it both ways." She suggested asking a trainer, who happened to be gone yesterday. In the meantime, I asked a 2nd programmer, who googled the name and found reference after reference of "Apples." I made the menu option say "Apples." This AM, the trainer wrote back that it should be "APPLES."
The point? There are always multiple opinions in regards to everything that comes up. If reading source code helps you do your job, by all means, read the source code. In my 14 years of experience - today is my 14 year anniversary of my first day @ job #1 - it is not essential.
No comments:
Post a Comment