Setting Up MadCap Initially

This forum is for all Flare issues related to getting started and installing the application.
Post Reply
lanteik
Jr. Propeller Head
Posts: 2
Joined: Wed Feb 01, 2017 8:36 am

Setting Up MadCap Initially

Post by lanteik »

We are about to go from being a MS Word house to a MadCap Flare house. We have had Flare now for over a year, but we have not yet forced ourselves to stop using Word and start using Flare.

We are in the process of setting up our project/folder structure and are struggling with how to set this up. We don't want to be in a situation a year from now where we have a mess on our hands.

Some questions for those that have been using Flare for a while:
- What are some of your pain points/lessons learned? What are some things you wish you would have done differently in the initial set up?
- What does your folder structure look like? What recommendations do you have?
- What do you think about having 1 master project vs. multiple smaller projects? What are the pros/cons of having a master project vs. smaller projects?
- Do you break up your content by audience, location, or projects?
- What does your naming convention look like?

ABOUT US:
Type of content we develop:
- Instructor and participant guides
- Exercise guides, data sheets, and practice guides
- Job Aids, Tour Guides, Quick Reference Guides, and other supplemental documentation
- We also create online learnings, but realize we won't be able to include this in MadCap

Who we develop for:
- Plants across 6 functional areas
- Corporate
- Shared Services Center
- Specialty Companies
- Information Technology Specific Projects that don't fall into one of the locations above
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Setting Up MadCap Initially

Post by Nita Beck »

You are asking some very important and very big questions! Hard to answer anything definitively, as doing so would require a lot more research and analysis. But I'll try to give some broad advice regarding at least a few of questions, and maybe others will add to conversation.
lanteik wrote:- What do you think about having 1 master project vs. multiple smaller projects? What are the pros/cons of having a master project vs. smaller projects?
Generally speaking, I tend to have one master project that contains all "corporate-level" assets: stylesheets, page layouts, master pages, images, snippets, topics (particularly things like legal content, tech support contact info and hours, tradename and service mark content, etc.). Anything that will be needed by all other projects belongs in the master project.

Then, I have a "child" project for each product, regardless of the types of publications the project might produce, be those traditional user manuals, quick reference documents, or online Help systems. The child projects import all the corporate-level assets from the master project. It's a given that some of the same content about a product will end up in more than one publication about that product, so best to have all the content in one project.

But this general scheme -- "master" corporate project and multiple "child" product projects -- might not be perfectly right for your situation. You might end up with a level in-between that addresses your corporate structure. For example, there might be "division-level" assets, best managed in a "division-level" project. So the flow of content would go from "corporate-level" project to "division-level" project to "product-level" projects. Or it might be "corporate-level" to "product-level" to "division-level". (Or, playing devil's advocate even more, there could be conditionalized "division-level" content in the "corporate-level" project that child "product-level" projects could selectively import or not. My point is that there is no one-size-fits-all solution. My point is also that this overarching architectural design needs to be carefully thought out. (It doesn't have to be perfect, but it does need to be thought out ahead of time.)

Gosh, I don't know if I'm being very helpful, but I thought I'd get the ball rolling. I'll try to swing back soon to answer another question or two.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
paintedturtle
Propeller Head
Posts: 88
Joined: Wed May 25, 2016 3:35 pm

Re: Setting Up MadCap Initially

Post by paintedturtle »

Welcome to Flare!
lanteik wrote: - What are some of your pain points/lessons learned? What are some things you wish you would have done differently in the initial set up?
We also moved from using Word and dabbling in Flare to Flare full-time. I wouldn't recommend spending time on importing Word documents--so much formatting is lost. What I do now (and what I would recommend) is creating a template for each type of document you'll be using (with table styles, formatting, and basic content already inserted) and then copying and pasting from Word into that document. Of course, if you have a huge variety of documents, that might not be helpful. But I've found that faster than importing from Word.
lanteik wrote: - What does your folder structure look like? What recommendations do you have?
Our manual has 9 sections, so I have a folder for the 9 sections within my images, multimedia, and the Manual section. Remember that Flare alphabetizes ALL files, so using procedure numbers can be very helpful for file structure.

Hope those ideas help!
Technical Writer using and experimenting with Flare version 12.0.5991.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Setting Up MadCap Initially

Post by Nita Beck »

paintedturtle wrote:... I wouldn't recommend spending time on importing Word documents--so much formatting is lost. What I do now (and what I would recommend) is creating a template for each type of document you'll be using (with table styles, formatting, and basic content already inserted) and then copying and pasting from Word into that document. Of course, if you have a huge variety of documents, that might not be helpful. But I've found that faster than importing from Word.
Oooh, for the most part, I don't agree, except for very small bits of content. (Sorry paintedturtle.) Yes, one needs to spend time up front prepping one's Word files (sometimes considerable time), but when one has a very large body of Word docs, importing into Flare is the much more efficient process.
paintedturtle wrote:... I have a folder for the 9 sections within my images, multimedia, and the Manual section. Remember that Flare alphabetizes ALL files, so using procedure numbers can be very helpful for file structure.
This kind of folder structure works particularly well for a Flare project that is print-centric and for a single print output (and I've used this structure myself). But for a project that is also intended to produce HTML5 output (or other forms of online Help/content) and/or other print docs with different TOC structures, this kind of folder structure is likely to be problematic.

A common method of organizing content is into topic types (conceptual, reference, task, and others as needed).
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Post Reply