The Glory Days

I didn't pay much attention to it, but I just crossed an anniversary that I really don't give a crap about remembering in 2015 or beyond. You see, it was just over 5 years ago, on October 18, 2010, that I began working at a company - not my current employer - as a technical writer. Let there be zero doubt that the absolute darkest period of my career as a technical writer was when I worked at that company. Indirectly, and without naming that company, 10/18/2010 - 4/13/2011 (177 days or 5 months, 3 weeks, 5 days) was not fun. If you put the puzzle pieces that I've scattered throughout this blog, you may be able to figure out the company, but it probably isn't worth the effort to figure it out.

Anyways, the reason for even mentioning this anniversary is that prior to working at that company, I worked at a company for a dozen years that used RoboHelp. Ah, the glory days. I went from having zero experience with that software on 10/1/1998 to being an expert with that software on 10/1/2010. I learned so much about its inner workings, how to manipulate files 'under the covers' that no one had previously documented or asked about. I even became a RoboHelp MVP because of the way I helped people through various RoboHelp forums. The kind of odd thing about that award and receiving a certificate from the CEO at a staff meeting at that company is that most of the time I spent helping other RoboHelp users was when I was at work. 'What would I have completed had I spent 100% of my time at work doing the work I was being paid for' is a question I cannot answer.

The only reason RoboHelp even came up is I received an email about an upcoming training session about content reuse. As of this moment, my current employer has zero chance of ever using RoboHelp to deliver our documentation. We are using Confluence and delivering our documentation as, essentially, a website that looks a lot like RoboHelp's WebHelp output. There is a TOC on the left side of the page and search functionality. We haven't implemented an index, but are starting to implement labels. We are writing 'system documentation' and, because of that direction, we are not writing customized documentation for each customer's instance of our software. Except when we are writing customized documentation for one of our systems. We told one customer that we weren't creating customized documentation and then, since this was a special situation, we went ahead and made a copy of the existing documentation and made the copy customized to the customer, including the names of buttons and tabs.

Just as a history lesson and because it's relevant, the majority of my daily work is writing for the "Next" version of a system. There is a "Current" version and a "Next" version. The customers that are using the "Current" version have traditionally received a customized user guide, delivered as a PDF. While the user guide for Customer A & Customer B may have the exact same system functionality, each customer user guide often differs in the editorial and content arenas. For example, one customer insisted on writing "Click the <ButtonName> button" whereas the Microsoft style guide, which we are using, says to write "Click <ButtonName>." That's the simplest example, but it is an indication as to why each customer's user guide is unique from the next. Another example is that two customers didn't want their customer support information available to any other customer. Thus, there are three versions: one is a 'base' version, one is a Customer A version where their customer support information is included, and one is a Customer B version where their customer support information is included. The rest of the document is identical. The net result of creating and maintaining documentation like this is that the work is doubled, often tripled, if there is a change to the content in one of the sections that is within the Customer A user guide and within the Customer B user guide.

That is why, for the "Next" version of the system, our direction has been to create "system documentation." To me, saying the phrase "system documentation" indicates that the user assistance is dedicated to "the system" and describing the tasks that any user in the system, regardless of permissions, job duties, or anything, can do. This has been a challenge to both write and, in some cases, convince co-workers of this approach's merits. Think from the perspective of a user of Microsoft Word. There is no 'customized documentation' for that product. For example, if you purchase Microsoft Word and someone, perhaps a system administrator (but it doesn't have to be someone who would list "system administrator" as their job title) has set up your installation to not allow you to change styles, you can still read about how to change styles. You can learn about how to do it, but, perhaps, there's a check box or a button that is disabled (you can't select or click it) so that means you can't actually do that task. At its most basic definition, that is what "system documentation" means.

I'm ecstatic that we use Confluence and (thus far) are not doing any customized documentation.

Except for that previously cited system.

Other than that, no, we are not.

Except that there's another system where my co-workers believe that users that are set up with a specific "role" (for example, Neanderthal) should not be able to see the documentation for tasks that another specific "role" (for example, Medical Doctor) can do. They want the Neanderthal to only see Neanderthal tasks. If the Medical Doctor is set up as a role that can do all Neanderthal tasks, plus other tasks, that is the set of tasks the user with the Medical Doctor role should be able to do. And, to make things even more complicated, if there is a third level of tasks that neither the Neanderthal nor the Medical Doctor can do, such as a role called "Medical Doctor Supervisor", then the Medical Doctor shouldn't be able to read about those tasks.

But we are not doing any customized documentation. That's good. Check back in a year.