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.
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.
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.
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.
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.
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.
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