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.