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.
Subscribe to:
Post Comments (Atom)
It's often more useful for a technical writer NOT to be an expert on the subject matter. There are many reasons for employing technical writers, but (in my opinion) the best reason is that engineers know too much about the subject to write their own documentation. A technical writer can approach the subject as an intelligent user, with questions, fears, and expectations similar to those of the target audience.
ReplyDeleteI compare it to an experience I had in college. I was enrolled in Math 101, College Algebra, an entry level class for first semester freshmen. My professor was a very quiet man who mostly had us working problems in the book. His lectures were full of formulas with very little explanation and he spoke very quickly and quietly. It was hard to believe he was a college professor, though I later discovered that he was, indeed. He taught a 400-level math class, Multi-dimensional Calculus. He had trouble explaining algebra to us, on a level that we could understand, because he was used to thinking in a realm so far above it. The algebra parts came to him the way that the alphabet comes to most any adult. It's hard to explain ideas that you take for granted at a basic and concrete level someone else can understand.
Many engineers have the same problem. They know what they are talking about, they can even explain it to someone with a similar background, but explaining it to someone with little or no knowledge of the subject is difficult.
We gain just enough knowledge to be able to "teach" it to someone else. We are the mediators.
I agree; it's good for me that my editor has been not writing for my products for a little while, so she can question my explanation of some things.
ReplyDelete