Skip to main content
Douglas_Campbell
Inspiring
April 20, 2011
Question

Structured Authroing: Enterprise Acceptance, Education, and PM?

  • April 20, 2011
  • 1 reply
  • 593 views

After some unusual experiences with a recent structured FM project, I wanted to turn to a community of peers to learn if others have experienced similar situations and what advice you might offer, if you have. Here is the background of the situation:

I was hired by a high-tech company to update a techincal manual almost two years ago. The company had about 6 to 10 very long internal engineering and customer-facing documents, almost all of which had been managed with LaTex for years. In an attempt to improve their documentation process, their former graphic designer/technical writer had migrated the documentation for their flagship product to InDesign. That decision wasn't too practical, as it was a 200+ page hardware and software user guide for a telecom device, something not well suited for a layout program. After taking care of their short-term needs with updates in ID, I explained the benefits of structured authoring to the project supervisor and subsequently my contract was extended to migrate all of their documentation to structured FM. This process went extremely well, largely because I was given a great deal of autonomy due to my experience in such projects.I wrote a custom EDD and templates that could be applied to all documentation and successfully migrated their legacy documents.

After that phase of the project ended, though, I found it very hard to properly manage their documentation needs, largely because of their ignorance and unwillingness to understand some of the basic needs related to structured authoring. I had made a concerted effort to educate them about structured FM all throughtout the migration, but my overworked supervisor considered my detailed reports as "too much information." Somewhere along the way, I believe she came to think of structured FM as a magic bullet of some sort and my explanations became misinterpreted as some sort of waffling, incompetence, or an attempt to pad hours. Really what my requests consisted of were nothing more than a development cycle that preceeded editing, a period that would allow me to manage any EDD work. It should be noted that the document in question was updated in parallel with a software release schedule of approximately 6 months and the management of this document alone was a full-time job for my predecessor. I reduced this process to a cycle of approximately 2 to 4 months per year, largely through the benefits of structured authoring that I don't need to detail here. Problems really began occurring when sales people and management started requesting last-minute, wholesale changes to the documents only weeks before deadlines, changes which required significant changes to the EDD. In my last deadline I received 200 marked-up pages of graphic and content changes two weeks before deadline while I was finalizing release notes and last-minute work. To get these changes done, I ramrodded them through and destroyed the structure of the documents and then had to go back and fix them thereafter. More specifically, I requested two weeks to rewrite the EDD and reauthor the 200+ page document and was confronted with increduility that it could takes so long -- and it was demanded that I complete it in a matter of days. I was actually told to make the "structure" of the document simpler, because "it's just a simple XML file after all" This company obviously had larger problems with their production processes and I was given no authority to change them, but I still find it difficult to grasp what I came up against in terms of acceptance, education, and management realted to structured management project requirements, especially when I explained it in such clear terms.

Certainly I would like to hear from anyone who cares to comment on the details of my experience. But more universally, I wonder if such obstacles are commonplace in your experience -- this was the first time I have come up against them. Also, when it comes to project estimation related to writing EDDs and doing development work, could you share your methodologies for coming up with timelines?

Thanks in advance,

Douglas

This topic has been closed for replies.

1 reply

Van Kurtz
Inspiring
April 21, 2011

Douglas,

I have to admit that I am rather poor at estimating how long a project should take. They say that one should record time spent on all work as one does it, and then use that information to estimate similar projects when they appear. I was fortunate in that the company for which I did my only EDD was very accommodating in the amount of time I spent doing it. Thus, I was able to test and retest the EDD every step of the way. The result was a very usable EDD that has served the company for four years now.

I am curious as to why those last minute changes would require rewriting the EDD. Did they request massive changes in layout and style? At that point in the life cycle, changes from SMEs are typically content only.

Van

Douglas_Campbell
Inspiring
April 21, 2011

Yes, the changes completely revamped the layout and styles. Beyond paragraph and character styles, though, it also profoundly affected the element/information mapping, this latter part requiring radical changes to the EDD.

Perhaps part of the problem was that the changes didn't come from the SMEs that usually just touch upon content alone, but rather largely came from sales and marketing executives, who decided it was time to make things "prettier" at the last minute, without understanding what it entailed.

Legend
April 22, 2011

Interesting discussion. I've had plenty of smart people either openly question or quietly doubt the logic of migration to a structured workflow. I think it is based on a simple misconception of how tech writers spend (or should spend) their time. There is this prevailing notion that they are mostly "writers," when in fact a large part of their job is normally to manage and publish information. In fact, some times the writing portion is equal to or less than the rest. Furthermore, it seems hard for others to understand how the efficiencies of a properly-designed structured authoring environment could make a difference during the authoring portion. It's not just how fast you type... it's how fast you can compose and organize the content.

When you are starting from scratch, it seems that you will always need to revisit and revise the process as bugs are found, sometimes heavily in the beginning. Perhaps you underestimated this and/or did not properly explain that point. If you do it right, the benefits will come, but not without the cost of some growing pains. In this situation, I think it is important to emphasize that it will take time to get the process ironed out and that major changes at any time will be burdensome. On the other hand, if you never stop making major changes, this points to a larger problem with consistency and continuity within the organization, something perhaps that makes all of this moot.

In my work, I have gone through major refactoring exercises with structure definitions/publishing techniques/etc. as requirements changed and/or became better understood. In my case, I've always been fortunate enough to have had the time to analyze and implement without hacking something to push a deliverable out the door. I don't think it was due to any particular genious with time management or proper estimation; rather, just general good fortune. So, like Van, I can't say I know anything about that part, but I do believe that you need to be liberal in your estimates and expect turbulence in the beginning. I have always been able to ultimately show the compelling benefits of the move in the end, but again, I've always had the right amount of time to do it.

Russ