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?