All aboard! Onwards to structured authoring!

Our team of technical writers is embarking on a journey towards structured authoring. With 10 writers, we’ll move from an unstructured Word to PDF/CHM environment to a structured Flare to WebHelp/PDF environment. Or I should say “semi-structured”: We do have an information model based on DITA, but we won’t actually be able to enforce it with Flare (which we knew before we chose the tool).

It’ll be an interesting cruise, to be sure! Four writers already apply topic-based authoring rather than the previous free-form documentation guided mainly by common sense. The others have had training, but no real opportunity to write topics continuously. We have drafted tighter new processes to draft, write, review and edit topics to replace the previous loose processes of writing and reviewing, but they are not in place yet.

And then there’s the new tool, of course. Only one of us has worked with Flare before. Many of us are excited about getting Flare. Some really like it – what we’ve seen in several demos so far. Others just really loathe the current writing environment.

“Regarding the pain of others”

So as we’re about embark, I’ve been looking out for others who’ve taken the trip before. Scriptorium’s State of Structure webcast has been very helpful: Its results of a survey among 200 tech communicators helps to position us in relation to others who are currently implementing structured authoring or considering it. It also collects some mistakes respondents have gone through. I’ll just be quoting a few select points, but the whole webcast by Sarah O’Keefe is totally worth checking out, so thanks to Scriptorium for making this webcast available!

Reasons

The top reasons why survey respondents (consider to) move to structured authoring made us nod emphatically: Reuse, consistency and cost savings are also at the top of our wish list of achievements. Looking ahead, it’s promising that the majority of respondents achieve these goals.

We’ll also take other goals that respondents achieved, whether it’s to automate processes or to reduce content (oh, yes, please, we’re not even exactly sure how much redundant, almost identical content we have). So far we’re confident, we’re not only doing the right thing, but doing it for the right reasons, too!

Efforts

Savings have their own price, of course. Sarah’s survey confirms several cost points we’ve already identified in the project.

  • Converting legacy content is a biggie for us, simply because we currently have a lot of stuff.
  • Redefining output layout will take time, but will be worth it given what Flare is capable of doing with CSS in both web and print outputs.
  • Integrating a new system with its writing and publishing processes into our product and workflow systems will also take some time.

Mistakes

Mistakes have been made by others before us, and we’ll have plenty of chances to make our very own mistakes. If we’re lucky, we can avoid repeating the mistakes of others:

  • Planning and project management cause problems, maybe because most companies lack the experience of major documentation overhaul projects. Sarah specifically mentioned the lack of understanding of the project scope and of the need for testing. So we’ll look through our project plan again and ensure that the estimates are plausible.
  • Converting legacy contents can also get you into trouble, especially when you convert something that’s less than structured. It doesn’t help if you reserve too little time to do it or get inexperienced people to do, whether it’s off-shore labor or student helpers. That’s sound advice: GIGO (“garbage in, garbage out”) can certainly endanger the expected benefits. A new tool can help us be more efficient, but we still have to learn and apply structured writing in topics. So this confirms one of my two tech comm dogmas: Don’t get a new tool to fix your processes!

Setting out

What do you think? Is our crew well-equipped, given a tried and proven method, well-defined processes, a new tool and the words of warnings above? If you have additional advice, please leave a message.

Advertisements

8 Responses

  1. My team has been using Flare for more than a year now. Flare is really very good. It is especially useful to produce printed and online documentation. You should be good to go with Flare with your team. Good Luck!

    • Thanks, Prajakta, for your encoragement. We are fairly certain we’ve made the right choice with Flare – but the project as a whole is a bit daunting… 🙂

  2. Kai, I’m glad to read that the survey results helped you make an informed decision about moving to structure. I’m thankful that people took the time to respond to the survey. Their shared experiences can help others make better choices.

    I’ve been working on the survey report the past few weeks; it expands upon the points Sarah brought up in her webcast. We will release the report in ePub and print formats by the end of June.

    We’ve included a lot of candid comments from respondents in the report. I’ll admit some of the comments made me groan because basic project management problems still abound.

    Another big problem we mention in the report: not thoroughly evaluating vendor marketing claims about tools. A few respondents didn’t mince words about their relationships with tool vendors.

    The report isn’t all negative, though! Many people reported meeting their goals for structured authoring–and even surpassing them. A smooth transition to structure is possible, but it doesn’t happen overnight. And it takes a LOT of planning.

    • Thanks, Alan, for your further insight into the survey’s results! As you can tell, I found the combination of numbers and comments highly useful, so thanks for taking the trouble of soliciting lessons learned and sharing them.

      While it may be disappointing to see people struggling with something comparatively elementary as project management, it’s certainly a welcome warning to people like us, because it can help us avoid these same mistakes.

      I didn’t mention your findings about vendor marketing claims for a couple of reasons:
      – We are fairly certain that we know what we’re getting with Flare, and snake oil is not involved. This is thanks to extensive testing on our part, but also because I think MadCap is honest about what their products can and cannot do and how best to use them.
      – I wanted to give away only some of the survey results (as I pointed out), so people have reason enough to get the webcast or report directly from you, rather than relying on my summary in what is essentially a case study in the making.

  3. > Or I should say “semi-structured”:

    Recently, I started to think about what the term ‘structured authoring’ means.

    Most ‘structured authoring’ is only ‘semi-structured authoring’. With structured authoring, the high-level structure is specified. However, usually, low-level structure is not specified. Some examples follow.

    1. Unless a controlled language is used, a document is not fully structured. (If the meaning of each term is not specified, then a document is not fully structured. What is the difference between ‘sometimes’ and ‘occasionally’ and ‘on occasions’?)

    2. However, a controlled language is not sufficient to make sure that a document is fully structured. If a controlled language is used, probably, both of the following sentences are permitted:
    * Give the XYZ report to your manager.
    * Give your manager the XYZ report.

    Fully structured authoring must specify the permitted sentence structures.

    3. Usually, terms are not tagged. Is a term a noun, an adjective, or an adverb?
    Fully structured authoring must specify the type of each term.

    • Thanks for your comment, Mike. I agree we are looking at two different levels of structured authoring here.

      In your terms, as a tech writer, I’m currently only concerned with specifying the high level structure, i.e., paragraphs and sometimes sentences. So the DITA-based information model regulates that each topic has a heading (and nothing visible to readers above the heading), and that each procedural topic has an introductory paragraph that gives context and purpose of the described procedure, and that procedures are given as a series of numbered (possibly nested) steps, etc.

      The reason I called it semi-structured is because our tools and processes, as selected and designed, will not be able to actually enforce that each topic fully complies with the model. I can certainly ensure that nothing appears above a heading in any topic. But I cannot guarantee that context and purpose are always present in the particular introductory paragraph.

      I stand by this decision because we’re coming from documentation that is rather unstructured on the topic level. So emphasizing structure to the extent that it determines the quality of the documentation doesn’t seem like a good idea. I’d rather measure the quality by its usefulness, whether it speeds up implementation and daily operations of the described system, not whether it’s fully structured.

      • Hi Kai,

        > I’d rather measure the quality by its usefulness, whether it speeds up implementation and daily operations of the described system, not whether it’s fully structured.

        I agree completely.

        The fully-structured authoring that I envisage is not practical for most technical writers. I was only ‘thinking out loud’ about the meaning of the term ‘structured authoring’.

  4. I haven’t ventured into structured authoring yet and don’t know if it’s possible; however, I am a huge Flare fanatic. Having been a user of numerous authoring tools/environments for 20 years, Flare has allowed me to single handed publish for 11 client-specific versions of two very large products, to include webhelp and pdf. I could not imagine going back to the horrors of Word, RTFs, help compilers, tweaking html, etc. Flare also integrates perfectly seamlessly with version control such as TFS.

    Sharepoint is a monster unto itself, especially if not configured on the server properly. It is not an out of the box application.

    Good Luck,

    BobB

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: