Two of my products are in beta right now. Both programs are generating feedback to the developers, which is very good of course. But the interesting thing I'm dealing with today is trying to fit new features/tweaks/bug fix documentation items into the existing structure of the documentation set. What I mean is, I've spent the past several months working with the developers and my manager to organize the documentation set in a specific way. (That effort brought its own challenges, which are kind of fun because they represent a larger LabVIEW effort to make the documentation easier to use, but I'll talk more about that in a later post.)
Anyway, now that beta customers' feedback is trickling in, the developers implement certain suggestions and then let me know I need to incorporate the new behavior into the existing documentation. Today I'm challenged to find places for these seemingly random tidbits of information that do not have a defined place in the existing structure. Sometimes I look at a what a developer says and think "Oh, I know exactly where that should go to make the most sense." Today though I've run into at least one beta-generated behavior change that doesn't fit anywhere. I'm reluctant to make a new topic for two reasons: 1) doing so calls the organization of the help file into question, and 2) an entire topic implies that this behavior is extremely important for the user to know, which might not be the case. Besides, a separate topic with one paragraph in it doesn't make much sense. I considered just adding a line to the "Known Issues" section of the readme file, but that implies there is a bug or something, which is not the case.
So part of the problem is that I don't know how much prominence to give to a certain change. Will users run into this situation often enough that this behavior merits its own heading? How will adding that heading affect the layout of the help file? Is this information related to the other information in this help topic? Questions like that. I'm glad that I have the freedom to even ask these questions and figure out answers in my own way. Sometimes, though, I wish I could just have a "Miscellaneous Information" help file with random tidbits of information about certain behaviors. The main LabVIEW Help has set a similar precedent with its "Caveats and Recommendations when doing X" topics, which is along the lines of what I'd like to do, but this particular behavior isn't a caveat or recommendation.
I'll figure out a home for this orphan piece of documentation, though. And in the future, I will look for ways to design more "flexible" documentation that can accommodate these tidbits better. I'm learning a lot from my first betas.
And speaking of random tidbits of documentation, Blogger apparently adds <p></p> tags to each paragraph, even if you don't specify them when editing raw HTML. Is that behavior documented anywhere?
I know exactly how that feels. It's important to find just the right place. The senior technical writer in my section is entirely inconsistent (the only thing at which he is consistent) in his creation of headings and sections in a manual. He will make this one Times New Roman 10 Pt, that one Arial 14 pt. There are typically five to seven heading levels in his documents and only four -- at most -- are needed for what we are doing. He uses heading levels that never appear more than once in the entire manual. It is frustrating. When I change it to a consistent, easy to navigate format, he makes me change it back and complains that I am making things too complicated and putting forth too much effort.
ReplyDeleteIt's very important to get the navigation tools right. Otherwise, no one is going to take the time to wade through the mess in order to find what they are seeking. I wouldn't. :D
------------------------
Speaking of HTML, I noticed something interesting about the National Instruments site. Visiting www.ni.com/labview/ and clicking on "View LabVIEW Demo" will produce the following results:
1. An "in-between" title appears in the title bar at the top of the browser. It states [See a LV Demo from LV Main - National Instruments]. It should read [See AN LV Demo from LV Main - National Instruments].
2. After about 5 seconds, it changes to [LabVIEW Demos - The Software That Powers Virtual Instrumentation - Products and Services - National Instruments].
It may be a small detail, but it is still part of NI's image. (I'm a dork, I know!)
A final thought: In the third sentence of the post to which I am responding, there is an extra "A" appearing before the word "what." (Don't worry, I won't pick apart your every post.)
Regards,
Kaylene
(feeling especially attentive to detail tonight)
Technical Writer, Frymaster Corporation
kbowden@frymaster.com
Yeah, consistency is a big thing here too. In fact, the LabVIEW documentation team members often disagree over whether or not consistency is more important than something maybe looking funny or out of place in a particular spot.
ReplyDeleteI have to say I find it amusing that a senior technical editor complains you're putting in too much effort. That seems strange to me :-) Maybe if he thought you were overworking yourself ... but complaining of too much effort seems wrong somehow!
Oh, and thanks for the comment on ni.com ... I don't work on that, but I filed a bug report to the web team.
I don't know how many companies you have ever interviewed with for a technical writing position (if you're lucky, just one or two). In Louisiana, technical writing is generally left up to the person with the least amount of job responsibility. They don't hire technical writers here. When someone is hired specifically for the job, it is not usually someone with a technical writing degree. So I work for a photographer/newspaperman turned technical writer. His grammar is not all that I would hope and he believes in just throwing something down and being done with it. This goes against every principle I have ever been taught (or naturally thought). Doing things accurately in a timely manner = good. His .PDF files have overlapping elements and often instructions are covered by photographs. And everything is in multiple columns!
ReplyDeleteThis diatribe has gone on long enough. Sorry. Have a nice day. :)
Out of curiosity, what program do you usually use: Framemaker, Pagemaker, or InDesign? Sorry again for complaining about my boss yesterday. I had a completely frustrating day, and he saved over all of my new files with old one. Then, he replaced the backups with the old files. Things are better today. I hope all is well at NI. It's Friday, afterall. ;)
ReplyDeleteWell, we (Tech Comm department) use FrameMaker for our PDF deliverables, but because we (LabVIEW) are software we use HTML Help to compile .CHM files for an increasing amount of our documentation. I imagine a fun blog post on that will be coming up in a couple weeks or so :-)
ReplyDelete