Is Doc-to-Help suitable as a tool for SMEs?

[mwright123]

Hello,

I work at a company that has a VERY large base of subject matter experts (SMEs) who author in Word, with just 2 tech writers who edit their work. Given this, we currently product 99% of our output in PDF (and sometimes it stays in Word format if it needs to be editable).

Senior Management has expressed a desire to move to "responsive," context-sensitive help PLUS print (for "old timers" in our customer base who are accustomed to printable output). However, they've also expressed a desire to see our SMEs retain the ability to edit the help files directly themselves.

Given both of the above desires, I am evaluating Doc-to-Help as an authoring tool. However, I am VERY concerned about giving SMEs the direct ability to modify the files, as they could end up breaking the help system, right?!

Has anyone ever seen this done - use of Doc-to-Help by the SMEs (in addition to the tech writers)?

Are there "safeguards" (e.g., permissions, locks, what have you etc.) that could be set up/configured to ensure the SMEs don't break things while they *substantively* edit content?

Thank you for any and all feedback!
Mary

[Rob Diaz]

I believe the Team authoring feature is what you'd use. This essentially relies on a source control system to take care of locks and version management. When a user checks out a document for editing, the lock is exclusive so no one else can be changing the same file at the same time. Depending on what, exactly, the nature of your edits are, this may be sufficient.

I suspect you'd need licenses for each potential SME/Author though. That could be costly, though I've never priced it out for more than the one user we need. I know you've seen my other posts about issues with the Team authoring, which are new issues in the recent past. I've worked around them by using TFS and Visual Studio to manage the checkin/checkouts, but that may not be a good solution if you actually have multiple users involved. When the team authoring features were working, it was pretty straightforward, as the checkouts occurred right in the Doc-to-Help application so there was little room to make errors.

Not sure if this helps or not. I hope it does.

Rob

[mwright123]

Hi Rob,

Many thanks for your feedback as an existing Doc-to-Help user. ...Based your experience as a user, do you see any problem with SMEs using the tool directly? My main concern is that they could "break" the system when they added content. For example, I read this in the Doc-to-Help online help:

<snip>
To make your Word document more useful for online output, it is broken up into smaller elements called "topics," which are based on the heading styles in the document (see About Topics). After you create a Doc-To-Help project and build some output from it (see Building Targets), Doc-To-Help automatically creates multiple topics as a result, structuring the content for online documentation. Heading 1 styles in your Word document automatically become parent topics, and all of the Heading 2 styles under a Heading 1 style become subtopics. Just keep in mind that these topics are not created until you build at least one target in your project.
</snip>

So essentially, if the SME does not absolutely, positive take care to use the Word styles, they could "break" the help system, especially if it were a context-sensitive help system, yes?

We can train our SMEs, but I am just curious as to potential pitfalls with them modifying the source files *directly.*

Thanks!
Mary

[Rob Diaz]

Hi Mary,

Well, my opinion is that you run this risk any time you have more than one set of hands on any document. So is it a concern? Sure. Is it *likely* to be a problem? Well, that depends on how well your SMEs follow directions and how often they make changes that would likely lead them to add or remove heading styles.

Back a few years ago when we did have multiple users, we had one "gatekeeper" who had to check that style and formatting rules and guidelines were followed and it was ultimately that person's job to handle the final build of the system.

As for context sensitivity, this is one area I think Doc-to-Help could (theoretically) get better at handling automatically. With one user we had some issues with topic ID numbers changing on us for no apparent reason (I'm sure there WAS a reason, it wasn't worth my time to try to figure it out). So, we went to manual topic ID assignment and our issues went away. If it is a concern for you, having someone responsible for assigning IDs may be the solution for you, too.

What do your folks currently do? Do they edit the word docs directly? Are you using any Source Control tools? Ultimately, I am a developer by trade so I rely on source control tools to ensure that if something goes horribly wrong we can roll back the offending change and figure out what happened. You'd definitely want that to be in place with many hands on the documents.

Hope this helps.
Rob

[Guser]

Hi Mary,

I am going through a similar issue where I've been tasked to find a software for 14-16 people who write docs but are not tech writers.

Without conditional text or snippets creating different flavors of the same document is too difficult. They also want the capability to produce online help eventually.

Flare, Robohelp, etc are too heavy for them.

Doc-To-Help and SmartDocs are the options that I think are the most feasible.

I just started the process. Do you see a major advantage of one over the other?

Thanks,

Guser

[mwright123]

Hi Guser,

We are still in the evaluation phase. I've had the opportunity to personally discuss the issue with a Doc-to-Help customer. In their workflow, they don't allow their subject matter experts (SMEs) to modify the files directly.

We are leaning away from this approach (SME use directly) at the moment.

Sorry that isn't much help - best wishes in the endeavor.

-Mary