Comments on: Why Help Authoring Tools Will Fade

By: Technical Writing News Nov 27th - Free Newsletter | I Heart Technical Writing

Mon, 04 Jan 2010 05:35:47 +0000

[...] Why Help Authoring Tools Will Fade [...]

By: Bonnie Kern

Bonnie Kern — Sun, 03 Jan 2010 20:05:15 +0000

Single-sourcing is a strategy, a methodology for generating multiple outputs from a single source of content, regardless of the number of technical writers involved.

Applying conditions to the content supports generating documentation for multiple products, platforms, and conditions, and the same content source can be used to generate content for various distributions including online and in printed form.

Single-sourcing allows you to enforce consistency, increase usability, reduce drift, and reduce maintenance. Single-sourcing works best when you have open-minded team members, a good content structure, source control, and a robust authoring tool such as MadCap Flare. To make the most of implementing single-sourcing of your content, your authoring tool or toolset must support single-sourcing to an effective level.

Regards,
Bonnie Kern

By: Tom Johnson

Tom Johnson — Tue, 15 Dec 2009 00:24:13 +0000

Derek, thanks for joining the conversation. I think we need to educate project managers more, because with some projects I’m on, they do bring me in early (and others don’t). One time I was brought in so early they hadn’t even determined what type of database to use. I said I’d check back in a month or so.

I agree that it takes a nimble tech writer to swoop in at the last minute and provide comprehensive documentation. On the other hand, when you approach a project at the end, without a history of meetings, planning, discussions, bug reviews, iterations, and so on, then you more likely approach the project as a new user. You can’t see a project with fresh eyes when you’ve been involved in it from the beginning.

By: Derek Warren

Derek Warren — Mon, 14 Dec 2009 17:50:50 +0000

I agree with you, Kevin. In fourteen years of writing documentation, I have had similar experiences to yours. I had been assigned specific projects–sometimes a few at a time–but always assigned as THE writer resource and usually assigned early enough in the project that I had time to immerse myself in it. I think you hit the nail on the head: “I think what’s ‘ludicrous’ really is the idea that someone can swoop in at the end of a major project and produce detailed documentation for it….” And yet, this is precisely how the organization works where Tom and I are both employed. In fact, when I first arrived here 6 months ago and pitched the value of involving technical writers in defining product terminology and writing UI texts, I had sold the general manager but was quickly executed by the lead product manager who insisted that the only place for technical writers was in the final hours of a project, after the design work was complete and development in it’s final stages of completion. So I’m suggesting that whether you empower a community of SMEs to write the content and the tech writer to do clean-up and production, or work as THE writer resource depends on the culture where you live and it’s willingness to adopt new processes. The project Tom referred to in his blog is the project to which I was assigned. I can only say that almost everything being done on the project has gone completely counter to my project plan (also a cultural issue). And yet the same project plan pitched to any of my prior corporate employers would have worked just fine. Thanks for your comments.

By: Destillat KW49-2009 | duetsch.info - GNU/Linux, Open Source, Softwareentwicklung, Selbstmanagement, Vim ...

Fri, 04 Dec 2009 08:44:57 +0000

[...] Why Help Authoring Tools Will Fade [...]

By: Kevin Amery

Kevin Amery — Mon, 30 Nov 2009 13:47:39 +0000

Tom,

I think you’re overstating things when you say “unlike developers, no writer ever gets to work on just one project” – that’s exactly what I do here. Of course, the main difference probably is that I’m a “captive” tech writer rather than a free lancer. I’ve been working with the same company for three years now, and I work on the development direction and testing of our product as well as documenting it. At this point, for about 95% of the product I’m my own SME because I know it as well as anyone else in the organization.

I think what’s “ludicrous” really is the idea that someone can swoop in at the end of a major project and produce detailed documentation for it, then swoop off to a completely different project. If you want to document anything effectively you need to know it, and you can’t learn something enormous to that level of detail in a few weeks. The problem isn’t the tools or the interactiveness of the workflow – the problem is the “outsourcing” business model for something that requires that degree of detailed knowledge.

By: Neil Perlin

Neil Perlin — Fri, 27 Nov 2009 21:04:08 +0000

I don’t agree that help authoring tools (HATs) will fade away; I do think they’re going to continue to change just as they’ve been doing for years.

First of all, I’d argue that the term “help authoring tool” is just a convenient way of referring to tools like RoboHelp, Doc-To-Help, Flare, AuthorIT, etc., but also a term that can limit how we think about these tools. (It’s telling that MadCap did not use the term “help” when they named Flare.)

Functionally, these tools went far past “help” authoring years ago. I’ve personally been using them since the early 1990s to create online books, tutorials, marketing materials, etc., as well as “help.”

We’ve also seen the tools expand their feature sets for years, adding point-and-click options for features that once required hand-coding in the source files. We’re seeing this extension again as the tools start supporting DITA. I *am* surprised that the tools haven’t yet added collaborative authoring features, but I expect to see such features in forthcoming releases.

Regards,
Neil

By: Technical Writing News Nov 27th - Free Newsletter | I Heart Tech Docs, Ivan Walsh, Technical Writer

Fri, 27 Nov 2009 17:29:56 +0000

[...] Why Help Authoring Tools Will Fade [...]

By: Paul Trotter

Paul Trotter — Fri, 27 Nov 2009 06:32:50 +0000

Hi Tom,

You can find more detailed information about Author-it Live on our Knowledge Center http://kc.author-it.com/#b7868.

Author-it Live is sold in both Small Business and Enterprise editions. The pricing starts at around US$15K. It is all installed on your own servers in-house. Hosted options are available if necessary.

We have just launched the SBS edition, see more information on my blog http://author-it.com/103fjq

BTW, teh Author-it Knowledge Center is all powered by a new Author-it product being released very soon called Author-it Aspect. It is a Dynamic Delivery Platform, for more info see:
- http://www.author-it.com/index.php?page=latestproducts
- http://kc.author-it.com/#b11510

If anyone wants a demo just contact our sales team sales@author-it.com.

Paul

By: Tom Johnson

Tom Johnson — Fri, 27 Nov 2009 04:38:09 +0000

Eddie, thanks for your comment. I agree that especially in highly regulated industries, a formal set of documentation at a specific snapshot is necessary, with only periodic reviews. I’ve never worked with that restraint. Usually the need has been to apply immediate updates to the content, rather than lock the content down from updates.

You mentioned that SME’s can collaborate to produce the quality content and then use a single-sourcing HAT to publish the content. However, I think that gets difficult technically. If you collaborate either via Word, a wiki, SharePoint, or X-Edit, and then pass on that finished information to a single-sourcing HAT, how do you make updates to the content after publishing the single-sourced information? Is that something you review at a periodic review cycle, creating new documents that highlight excerpts that need alteration?

It seems easier to keep the content in one source, rather than transferring it to another tool, and so forth. But you make a good point.