Tag Archives: Word

Getting to Know Doc-To-Help with the Sample Projects

Doc-To-Help includes 11 real-world sample projects that are a great way to learn more about how Doc-To-Help works and demonstrate best practices, as well as give you inspiration for future projects. These sample projects use both editors (the built-in HTML5 Content Editor and Word), and include examples of software documentation, an employee handbook, training materials, Responsive Help, and API/SDK documentation projects. There is even a sample in German.

The projects are:

  • All About Pittsburgh (in both HTML and Word versions)
  • API Documentation (HTML and Word versions)
  • Berlin (German language version in Word)
  • Brew Crew Answer Station − a resource for coffee delivery service (HTML and Word)
  • Employee Policies (Word)
  • Software Documentation (HTML and Word versions)
  • Training Materials (Word)

These samples demonstrate:

  • How to structure a project for single-sourcing. Examples cover writing book chapters in Word AND using topic-based authoring in HTML.
  • Many features − links, conditional text, variables, expanding/collapsing text, glossaries, and more.
  • Working in either source document type (Word and HTML)
  • Responsive NetHelp

Each sample includes a document named “About this sample” that explains the purpose of the sample, the use case, and tells you exactly which Doc-To-Help features are used in the project. The “About this sample” document is marked with the “Internal” condition, so its content will not appear in any of your final Targets. (You may want to use this condition in your projects; it is just one of the conditions you can use to single-source more efficiently.)

In addition to that, the samples include information that you can use in your work … the Software Documentation sample includes information about the requirements of software documentation, how to plan a project and structure it, as well as how to implement context sensitive help.

The Employee Policies sample is an example of an actual handbook and includes topics commonly found in an employee handbook. With Doc-To-Help, you can create a NetHelp version (NetHelp is our browser-based output) and put this information on your company’s intranet. If you choose to create Responsive NetHelp, your content will adapt to the device, and be touch-enabled.

The API Documentation project is an example of an API reference documentation project. It includes a reference section automatically generated using the Doc-To-Help Sandcastle plugin, as well as additional narrative content that links to the reference section.

There are two “Pittsburgh” samples. They are identical in content, but their source documents are authored in two different editors: Word and the built-in HTML5 editor. They include a wealth of information about the home of Doc-To-Help, and demonstrate a number of commonly-used features.

To open the samples:

  1. Choose File > Open Project.
  2. In the “My Doc-To-Help Projects” folder, open the “Samples” folder.
  3. Open the appropriate sample folder.
  4. Select the .d2h file and click Open.

Or click the Getting Started Wizard button in the upper right  Getting Started Wizard and choose Open a Sample Project.

Getting Started Wizard Samples

The projects are stored in the following locations. If you would prefer, you could make a copy of the Samples folder before you start manipulating the samples. Then you can experiment with them to your heart’s content and still have the originals to refer back to.

The sample projects are stored here:

  • Windows 7/8 and Vista: \\Users\<username>\Documents\My Doc-To-Help Projects\Samples
  • Windows XP: \\Documents and Settings\<username>\My Documents\My Doc-To-Help Projects\Samples

Enjoy learning Doc-To-Help with the Sample projects. Please see the Video Library for quick video overviews of how to use Doc-To-Help.

Troubleshooting “Compile Error: Cannot Find Project or Library”

Recently many customers inquired about an error “Compile Error: Cannot Find Project or Library” that pops up on trying to open an existing word document in order to make a change in the text.

The key to this error is the DocToHelp Global Constraints message.  If you get that, it points you to the Global Templates.  Both C1D2HAuthor.dot and C1D2HEngine.dot should be checked in that dialog.  If one (or both) is unchecked, make sure both are checked.

You can resolve this error by following simple steps :

  1. Open the Word document and go to the File menu in the toolbar.
  2. Click on Options and then Add-Ins from the Word options dialog box.
  3. Choose Templates from the drop down for Manage and click Go.
  4. In the Templates and Add-Ins dialog box that appears, if one (or both) of C1D2HAuthor.dot and C1D2HEngine.dot template is unchecked, make sure both are checked.

CheckCD2HAuthor

 

Interview with Rick Kossik (Doc-To-Help Podcast Series #8)

In this interview, I chat with longtime Doc-To-Help user Rick Kossik about single sourcing a large, modular documentation set. Rick has over 1,500 pages of source documents (he authors in Word) – and uses Doc-To-Help to deliver nine user guides and a context-sensitive, modular Help system for a powerful simulation software package.

To listen, go to:  Doc-To-Help Customer Interviews … or read on.  ♥ Nicky

Nicky: Hello, everyone. Welcome to the Doc-To-Help podcast series. I’m Nicky Bleiel, and today my guest is Rick Kossik from Issaquah, Washington state, which is very close to a more famous city called Redmond, Washington.

Rick Kossik:  Hello, Nicky. Great to be with you.

Nicky: Rick, it’s nice to have you. You’ve been using Doc-To-Help for almost 10 years now. So tell me a little bit about your company. I know you work in the software industry.

Rick: Yes. We’re a small software company, GoldSim Technology Group, and we develop GoldSim, which is a powerful simulation package. It’s used to simulate complex systems. Most of our customers are engineers and scientists. It’s used by many government organizations. NASA uses it to simulate space missions. The Department of Energy uses it. Many large engineering firms use it. It’s quite popular in the mining industry. Research laboratories use the software. We’ve got customers in over 30 countries.

We started developing the software in 1990. We were part of a larger engineering firm at the time. We spun out, formed our own company in 2004. And I’m one of the founders of that company and have been working on the product since the beginning, over 20 years ago, and I’m the one who designed and developed the user documentation.

Nicky: That’s really cool. I used to write documentation for a simulation product also, and it’s a very highly technical audience. Tell me a little bit about the deliverables you provide for them.

Rick: Yes. It’s a different type of tool because, as a technical product, our users really expect a high level of documentation. And we put a huge amount of effort into our documentation. We provide printed documentation, which maybe not too many people do anymore. We’ve got about 1,500 pages of printed documentation. We provide these as PDF documents, and we also print them and deliver them to our customers when they buy the software.

We also have an HTML-based help system that essentially consists of all of the documentation that’s in the printed system with the exception of the technical appendices. So those are the two types of documentation we provide:  the printed help and the HTML help.

Nicky: Very impressive to hear that someone is printing books for software documentation. That’s very cool. So with Doc-To-Help, you get an output that suits that. It could go straight to print.

Rick: Yeah, absolutely. In fact, it’s quite important that we have the single-source capability of Doc-To-Help. We have a large single source. We can create the manuals and the online help from one source. It works great for us. We also use a modular-help system and we take advantage of the modular-help capabilities of HTML help.

Nicky: Right. In addition to your manuals, you do modular help, which means you have a core help system and then a help system for each product.

Rick: That’s correct. And we have multiple modules that come with the software. We have our basic framework, and then we have specialized modules that can be purchased separately, and each one of those modules has its own help system and its own printed manual. The modular-help approach allows us to create a separate CHM file and a separate printed manual for each one of these modules.

Nicky: Right. So a modular project, just to jump back and talk about the concept of it, it is just what you said: it’s multiple help files that exist separately and are usable separately but get rolled up into a single project. And this is really a great way to develop a help system for a product like yours. It’s flexible. If a customer doesn’t buy a certain product, that help can be excluded from the install. And it’s seamless. If the end user doesn’t buy something, that little bit of help is left out. If they do buy it, it snaps back in. I know that that is one very good reason to use a modular-help system, which is very easy to create in Doc-To-Help.

There are three or four good reasons to create a modular system. You use a different approach. So why don’t you tell us about that?

Rick: Yeah. The main driver for our modular-help system is because we have this large amount of documentation provided in which each particular module had its own separate manual, and I really wanted to keep those separate from the developers’ side to organize our documentation.

We actually provide, in the help file, all of the CHMs to our users. Even if they don’t purchase a module, the CHM is available for them to look at. And we view this as a marketing opportunity. So they’ve got the basic framework, and now they can start looking through our help system and say, “This is a really cool module. Maybe I need to purchase that module, too. It would give me capabilities that I don’t know about.”

We take a slightly different approach there. We actually provide all of our CHMs to the user. In fact, all of our PDFs are also available on our website, so anybody can go and look at our documentation, even if they haven’t purchased the software.

Nicky: I did want to mention, I took a look at the user guides on your website. They’re very comprehensive, and they’re very well done.

Rick: Thank you. We’ve put a lot of effort into them. And in the long run, actually, I think more companies need to put more time into their documentation. It really serves two great purposes. One, it keeps your customers happy; they like good documentation. And two, it actually reduces the amount of support we have to provide, because if I have explained something quite thoroughly in the documentation, that’s a support phone call that we don’t have to take because the person can already see that information directly in the help file.

Nicky: I completely agree. And in addition, you make it easy for your users to find your help, because the help system is context-sensitive.

Rick: Yeah, that’s critical. We’ve got thousands of dialogs built into our software, and each dialog is context-sensitive and will jump to the appropriate part of the help file.

Nicky: Right. And since you’re using modular help, the context sensitivity still works within a modular project. So I just want to let everyone know, one doesn’t exclude the other.

Backing up a bit, I never actually asked you. You said you have 1,500 pages of documentation. I never asked what editor you author your content in. Do you use Word?

Rick: Yes, we’ve always used Word as the editor.

Nicky: OK, cool. So you’ve been using Doc-To-Help for almost 10 years, using Word as the editor, and you’re getting what you need.

Rick: Absolutely.

Nicky: Are there any other Doc-To-Help features or options that you really like that you’d like to talk about?

Rick: Well, the software is so easy to use. Particularly in the last couple of years, I noticed things build quite quickly. You guys must have made some nice changes there, because I used to have to sit for a while as I built this 1,500-page document. It’s certainly quite efficient in that regard. But by far, the most powerful feature that I just couldn’t live without is the single-sourcing capabilities. It’s so easy to take a single source, divide it into my multiple targets, and build whatever target I want.

Nicky: I really enjoyed talking to you today, Rick, and I thank you very much for being our guest in the Doc-To-Help podcast series.

Rick: All right. Thanks a lot, Nicky.

Nicky: If you would like to see why Rick has used Doc-To-Help for so long, please download a free trial from doctohelp.com  and try it out. Thanks, and I’ll see you next time.

– 30 –

Download a free trial version of Doc-To-Help here: http://www.doctohelp.com/

Recorded September 2011.

Interview with Mary Connor (Doc-To-Help Podcast Series Episode #6)

In this interview, I chat with Doc-To-Help user Mary Connor about how Doc-To-Help fits perfectly in her Agile workflow, migrating from Author-it to Doc-To-Help, Team Foundation Server, SharePoint, API Reference documentation, automating Doc-To-Help builds, localization, and more. To listen, go to:  Doc-To-Help Videos, Podcasts, and Screenshots … or read on.  ♥ Nicky

Nicky: Hello everyone, and welcome to the Doc-To-Help podcast series. I’m Nicky Bleiel, and today our guest is Mary Connor of Advanced Solutions International in Austin, Texas. Welcome Mary, and thanks in advance for sharing your Doc-To-Help expertise with us today.

Mary Connor: Oh, hi Nicky, and thanks so much for inviting me.

Nicky: Oh, no problem. Now first of all, tell me a little bit about your company.

Mary: Sure. It’s called Advanced Solutions International. It’s a 20-year-old private global company. We’ve got about 200 folks, and we make membership and fundraising software for non-profits. Our flagship product is called iMIS.

Nicky: Oh, OK. So obviously you do software documentation. You’re a software shop. You recently switched from the Waterfall methodology of software development to Agile. Could you explain a little bit about how that turned your documentation process on its head?

Mary: Well, one of the big deals for us is that our style of Agile means there’s no lagging. So we have finishing documentation as part of “definition of done” of each little two week sprint. And that, if there are docs that aren’t done, that blocks the entire team. And we don’t get to integrate all of our docs together until the final regression spread.

But one of the things that really blew us was a new house rule: that everybody on a sprint team is going to be a cross-functional generalist. Everybody’s going to be a product developer.

Theoretically, everyone can and should write documentation. So we needed something like Doc-To-Help to let everybody author in Word. So that all of our subject matter experts could contribute.

And the other piece is that we have TFS integration. All of our source control, and all of our backlog is managed in Visual Studio. And we can also manage all of our documentation source there now. So lots of things have changed.

Nicky: Wow, yeah. [chuckles] That is quite a bit of change at one time. Somebody really moved your cheese.

[laughter]

So the switch to Agile meant you added tools obviously. You were using Author-it and you migrated to Doc-To-Help. So can you tell me a little bit about that?

Mary: Yeah. I wasn’t worried, because I had a lot of experience migrating to different tools. My experience is getting well styled, structured content into a content management system. It’s pretty pretty easy, but getting it out can be kind of hard.

So, what I found is that we had chopped up all of our content not by topic but into larger units. Which I call reusable learning objects from my instructional design background.

Because we had done that, I was able to find all of the chunks and export books, include them only once. And flatten out all the content and get all the content out without losing it and without duplicating it. That was a big trick.

The other big trick to pulling this off was taking the time to write some batch files and macros. That automated the entire process of doing the export out of the Author-it database into intermediate files. Doing the import into Doc-To-Help, doing builds and testing.

And being able to try something out, go through the entire process. Push the button, look at the output and then make a tweak and run it again. And that was huge. As soon as we did that, then the speed of the whole process really picked up in the migration.

Nicky: Cool. So definitely doable then is what you’re saying.

Mary: Oh, it’s doable.

Nicky: Great. Obviously you decided to move to Doc-To-Help. What are the big picture features that sold you on Doc-To-Help?

Mary: OK. Well, Agile was just half of the pain that we were looking at. We had a whole lot of other pain. The other pain was how the product changed, and that all of our new documentation could not be authored in our Author-it database. But Doc-To-Help could, and that was really key. Doc-To-Help could do API reference documentation.

And the other thing it let me do was to reference a whole bunch of new external HTML files that were being authored up in the code and include that in our documentation. I could not have done that in Author-it. So that totally changed my deliverables. Now I could have one tool that covered all of our deliverables.

But the other things, too, had to do with single sourcing across all of our targets. It could do our manuals, our websites, our help files. And we could blend our sources, some of our sources in HTML, some was in .docx files, which is the Word XML format.

The other huge thing as I referred to was that we got one strategy that covers all the end user documentation and all the API developer documentation. And that’s just wonderful.

It has a lot of great team features, the integration with TFS and with SharePoint. And the fact that people can use whatever editors they’re comfortable with is really important for getting everybody willing to participate.

A deal breaker for me, Doc-To-Help has command line builds. It’s got a build scheduler. That was an absolute. That has to be there to move at the speed of Agile.

And the other thing, too, and this is not a small thing, is that it could handle the size of my builds. Our builds are immense, absolutely immense. And that it was able to handle it, and the fact that we could afford it. So, all great reasons.

Nicky: Wow! That’s a lot of stuff. I was going to interrupt you, [laughs] but you really went through a lot of features there.

Mary: [laughs]

Nicky: I’m glad it works for you. Like you said, all that and you have a very, very, very large project.  I put enough “verys” in there I hope.

Mary: [laughter]

Nicky: Now, you have one more thing you’re going to be doing, adding to your list of things to do, is tackling your first translation project later this year. How do see Doc-To-Help fitting into that process?

Mary: Beautifully, actually. In fact, before we migrated to Doc-To-Help we weren’t even talking about localization. So this just popped up this year. We’re looking at our first localization project. We were talking about German, but actually French Canadian might get in there first.

The beautiful thing is that Doc-To-Help integrates with SharePoint, which you can use for translation management. And so, we’re totally counting on that. The fact that we can manage our source in Word means that we can work with all those great internationalization and standardized technical English tools that are out there, which will help us save money on our localization.

So our goal is to use Doc-To-Help with that SharePoint integration to automate our builds across all these languages. So, we’re excited to get working on that.

Nicky: Great. Yeah, and that is really cool that, not only did you get a feature that you weren’t really thinking about using at the time. But also you’re going to end up saving money. Because translation, of course, is very, very — more verys — expensive.

[laughter]

But at the end of the day, you really use Doc-To-Help to its fullest. I’m very impressed with all of the features that you take advantage of.

Mary: Oh it’s a very powerful and flexible product. I would say that it has tons of features that we’re not even using yet. Seriously.

Nicky: I know.

[chuckling]

Mary: There’s also another possibility, just popped up this past week. That maybe we’re going to switch from using TFS as our repository to using SharePoint as our repository for our team editing. So that’ll be fun doing that migration. But it’ll be fine.

Nicky: Right and yeah, you’re all set up for it because Doc-To-Help has the interface to SharePoint. So, perfect.

Mary: Yeah.

Nicky: Great. Well, Mary, this has been interesting and a lot of fun. I thank you very much for joining me today. And I also thank all of those in the audience who are listening.

Mary: Oh, my pleasure. Thanks so much for having me.

Nicky: Yeah. I did want to mention, if you want to hear more about this project. Mary has been blogging about her company’s migration to Doc-To-Help on her blog, which is CleverHamster –as in the rodent–.com. So check it out if you’d like to learn more about her project.

And, if you want to try Doc-To-Help, please go to DocToHelp –one word– .com  and download a trial today.

– 30 –

Download a free trial version of Doc-To-Help here: http://www.doctohelp.com/

Recorded May 2011.

Bloggers note: Mary and I will be giving a talk about API Reference doc at LavaCon — hope to see you there: http://lavacon.org/sessions/double-trouble-adding-developer-docs-to-your-deliverables

Time-Saving Features in V2

Along with all the new features in Doc-To-Help 2011 V2, we enhanced some existing features and added some new elements to the UI as part of an ongoing effort to make your life easier.  Whether you’re a new customer or a long-time user, I think you’ll find the new additions will save you time and (possibly) aggravation.

Doc-To-Help 2011 V2 is scheduled to release on August 30th, 2011.

Here’s what we added:

Project Enhancements:

Themes are now stored in My Documents.

Previously, Themes were stored in the install directory, which is located on the C: drive.  For Windows Vista and Windows 7 users, this meant that they needed administrative permissions to make changes in those folders.  They needed to run Doc-To-Help as an administrator in order to use the Theme Designer.  Also, since new Themes are written to My Documents, you don’t need to move anything after you upgrade.  Just open your project, upgrade the Theme, and get to work.

Two other notes:

  1. The folder location is actually user-specified, so you can set it to a network drive that backs up every night.  That way, you won’t lose any work.
  2. The only time you need to run Doc-To-Help as administrator at this point is when you first license the software.  All features now no longer require full admin rights.

Added “Title” Property:

Now, there’s one place to change the caption or title for every target in your project.  By default, it’s the name of the project, but you can set it to be whatever you want it to be in Project Settings.  No matter what you build — HTML Help, NetHelp, WinHelp, JavaHelp, Manual, Help 2.0, MS Help Viewer 1.x — whatever’s in the Title field will serve as the title of your output.

Improved Project Styles:

Your Project Styles will now be synched with the styles in your Word template.  If you create a new style in Word and need to create a corresponding style in Doc-To-Help, you can now choose that style from a dropdown and the settings will be inherited from the Word template.

For international customers, this means the locale settings will carry over, too.  Language settings in Word and settings in Doc-To-Help will no longer be at odds with each other, which makes it easier to translate your projects into multiple languages.

Build Improvements:

  1. The Build Scheduler has been extended so that it runs through Windows Services.  You can automate  builds through the scheduler itself, or through command line.
  2. You also automate builds for projects that have a .d2hx extension, which means that Team Authoring projects and Team Foundation Server projects can be scheduled as well.
  3. We have improved diagnostics for external compilers and improved error reporting in general.  That means you should get fewer errors when you build and, if you do get an error, the message will be more descriptive.
  4. In the Output window — which shows up after you build — there is a link to open the Build Log in order to report errors and a link to the Forums to research any errors that have occurred.

NetHelp Improvements:

In addition to adding a more customizable, flexible version of NetHelp in NetHelp 2.0, we’ve made some general enhancements to the output.

  1. You can now link to Keywords and Searches in the NetHelp target.  When the link is clicked, NetHelp opens with search results displayed.  This gives you the ability to send links to exactly the information you want people to see.  It improves find-ability and customer satisfaction.
  2. You can change the Default Extension of topic files in your NetHelp output.  Right now, it’s set at .htm, but some customers have asked for the option to be able to change it to .aspx so that they can add the security features inherent in that extension.
  3. If you have created XML Transforms for your NetHelp targets, you now specify specific Transform files for specific targets.  If you haven’t created any XML Transforms, check out that feature because it’s pretty cool.