On Expertise

When the TTU students visited last Thursday, one of the questions they asked was how much of an expert tech writers are expected to become on the products they document. My answer was "we're not engineers, but we're intelligent enough to deal with engineers, understand their features and products on an abstract level, and make decisions about how those features/products affect the user." I found this comment applicable to a particular situation I'm facing, which is explaining to users the rationale and functionality of the Kalman filter.

Not being an engineer, I've heard very little about Kalman filters. I hear they were instrumental in the US space missions in the 60s, especially the lunar landing. There is a section in the Control Design User Manual where we talk about the CD Kalman Gain VI, the one that you use to calculate the gain L to apply to a Kalman filter for a particular model/noise covariance. I wanted to expand this section because I feel it's particularly nebulous as to the purpose/functionality of a Kalman filter and because users can benefit from knowing why they are using this VI.

I started with some example programs we shipped in CD 2.0. Looking simply at the VI's inputs and outputs, as well as the current documentation (written by my manager), helped me understand what was going on. These resources were both extremely helpful. By seeing what inputs are required to the VI and comparing those to notes from my developer(s), I could craft some sort of explanation as to what was going on.

Unfortunately, I was wrong in several key areas. When I sent the new documentation to review, I received it back covered in enough red pen to make my 10th-grade english teacher proud. Mainly it was technical stuff the developer wanted to add to avoid confusion; but I made several assumptions that turned out to simply not be true.

We met, and he explained to me what was going on, where I went wrong, and what he'd like to tell the user. He drew several diagrams, complete with equations, that I kept. I countered with what I felt was appropriate for the user manual section. Pretty soon that "ah-ha!" lightbulb moment happened in my brain, and we agreed on some common ground for the user manual.

So now I have a new understanding of the Kalman filter, albeit on a fairly high level. The point here is that I am not an expert on the Kalman filter, control theory, or software engineering. But I am intelligent enough to work with the developers to reach a common high-level understanding of what's going on, propose how I will explain this to users, and move on from there. When I hand a document to the engineers, it is with the request to "make sure what I'm saying is correct as it pertains to this product and the functionality we offer."

To be fair, I've known all this since day one, at least implicitly. But for the past few months I've been finalizing documentation sets and not necessarily researching/documenting new features, so I haven't been in the practice of the formal review cycle. I take each review cycle as an education in the theory behind my product because I learn so much each time. It helps to have developers who are very good about working with me towards a point from which we can both communicate to the user.

More Members!

I'm happy to announce that several other technical writers/managers in the LabVIEW group will be posting to this blog. The blogging revolution at NI continues :-)

LabVIEW 8 Help Online

Those of you who are curious (or in need of assistance) can now view the entire LabVIEW 8.0 help file online. Before we were just posting PDFs and CHMs. The problem is that Google and ni.com's search engine can't access the internal text of these file types. All you could search was the abstract. But now that each help topic is a single HTML page, search engines can index that content so it's easy to find.

The toolkits and modules should have their help online too, I'm just not sure when.

Last Wednesday (October 26th), another tech writer and I woke up extremely early and drove down to UT San Antonio. We presented information about NI and technical writing to three technical communications classes. UTSA's tech comm concentration is a part of the Communications department, as opposed to some other universities where the tech/professional writing program is a part of the English department. That's part of the challenge with recruiting from universities; the tech comm / English departments are in various states of completion and organization (not to mention funding).

The trip was a lot of fun. The other writer, Lori, and I covered roughly the same topics in each class, although we tailored the approach to the subject of the class. For example, in the Writing for New Media class, I spoke about the move towards HTML-based documentation vs. the tradition of PDF-based documentation. In the design & layout class, Lori contrasted the layout of the cRIO hardware documentation with the layout of the fold-out posters for applications like Measurement Studio. I talked mainly about the atmosphere and culture of NI, for which we've won awards (come to think of it, I didn't mention the FORTUNE 100 awards. I will next time.) I also got to explain the Control Design & Simulation products I document. That was a first for me, as I have spoken only to friends and family about the products, never to a larger group. I hope my descriptions were accurate ;-)

Basically, we tried to give an impression of what technical writing life is like at NI - working with engineers, researching upcoming products, organizing the documentation, performing usability testing, things like that. We emphasized that the job is not just sitting in front of a computer and entering edits. Of course, that's part of it, but in the long run just a small part.

Although the trip fell under the umbrella of recruiting, the goal of the trip wasn't necessarily to recruit students. We mainly wanted to see how interested the students/faculty are in having us come down every so often. Judging from the response we got, I think we were successful and should continue to visit their campus in the future. In each class, students asked us questions after we'd finished speaking, which showed us that the students were at least curious about tech writing as a career. We left some surveys with the professor so the students could tell us their opinion directly.

The whole trip was fun. I like that technical writers initiate and manage the interview/recruiting process, as opposed to leaving everything up to HR. I definitely look forward to doing more recruiting events. Next week, the STC chapter from Texas Tech is visiting NI. I'm involved with showing them around (and taking them to dinner, of course!) so I'll post about that after they visit. We have a bunch of tech writers from TTU; in fact, I think I'm the only one in the group who didn't go there. Oh well, they'll just have to forgive me for going to another Tech :-)