Getting Started Right - A Few (hopefully simple) Questions

[dapellegrini]

Hello All,

I have been reading through various posts on this board and happy to find a healthy community of fellow users interested in sharing experiences and expertise. I hope to be able to add more once I get over this daunting intial learning curve.

I am new to Flare, just licensed the MadCap Pack or whatever it is (the bundled version) to manage our software documentation. We currently maintain about 40 user manuals in Word 2003 format. My job will be to bring these documents into Flare, standardize them, restyle/modernize them, and then publish them as online WebHelp as well as Print Manuals. In all we have roughtly 12,000 pages of documentation across 40 documents, including about 10,000 images / screenshots. Obviously I have my work cut out for me.

I am hoping for some pointers and advice in setting this up right from the get go. Here are some of my current questions:

1) Should I create a Flare project for each Word Document and link them together later, or put them all in one large project?
2) Are there some simple things I can do to my Word files before importing that will make clean-up easier?
3) How do you all manage the update and software versioning process? Make a copy and edit for new releases?
4) What is the best way to accomodate document updates and edits - we have many folks writing and updating the documents and I am the only one with Flare

I will need to publish multiple versions of the help system - one large all inclusive WebHelp and various break-out groupings. In print I will need various groupings of what are now multiple documents.

Thanks!

- Dan P.

[SteveS]

Hi Dan,

Welcome to the forums

1) Should I create a Flare project for each Word Document and link them together later, or put them all in one large project?

I find maintaining a Flare project for each document the best approach, although keeping track of stylesheets is a bit of a pain. I have an excel spreadsheet showing which stylesheet, masterpage etc I have modified and copy it to all my projects eac Friday (or when publishing). There is a suggestion Flare IV addresses this issue by using a master project for the repeated content.

2) Are there some simple things I can do to my Word files before importing that will make clean-up easier?

There are quite a few posts in this forum about Word imports. Best advice - get the Word stuff as clean as possible, experiment with the import settingss and when you get it right, archive the Word documemt. Permanently.

3) How do you all manage the update and software versioning process? Make a copy and edit for new releases?

Again, my spreadsheet keeps a track of the current version and whether I've published. Each project has a version history topic (which may or may not be included in the output).

4) What is the best way to accomodate document updates and edits - we have many folks writing and updating the documents and I am the only one with Flare

Nightmare (for anyone using a different tool to the authors, not just Flare/Word), Its bad enough with everyone using just Word - someone knows better than the style guide and will create their own styles...

I'd try and get them to send unformatted text and you apply the format after you get it into Flare.

HTH

[LTinker68]

1) Should I create a Flare project for each Word Document and link them together later, or put them all in one large project?

I think it depends on if each Word document is its own help deliverable or if multiple Word docs make up one help package. If it's the former, then I'd create a project for each document, unless there is a lot of shared content between the help. If it's multiple Word docs per deliverable help, then I'd create one project for the package and import each Word doc one at a time.

2) Are there some simple things I can do to my Word files before importing that will make clean-up easier?

Simpler is better. That said, if you're not going back to the Word doc after you import the file (i.e., you'll never import it again), then you can just as well do the cleanup from within Flare.

3) How do you all manage the update and software versioning process? Make a copy and edit for new releases?

Some people use source control so that they can keep track of changes from revision to revision. If you just want to give the user an idea of what version they're viewing, then you can just write a version number on the "welcome" page and update it every time you deliver the updated help.

4) What is the best way to accomodate document updates and edits - we have many folks writing and updating the documents and I am the only one with Flare

Check out the X-Edit products that MadCap will be releasing (hopefully shortly) -- http://www.madcapsoftware.com/products/xedit/.

I will need to publish multiple versions of the help system - one large all inclusive WebHelp and various break-out groupings. In print I will need various groupings of what are now multiple documents.

Read up on conditional tags and targets. And snippets. You can have one project and have multiple skill level versions that you build (basic, advanced, for support, etc.) and have multiple output options (WebHelp, print output, etc.).


Welcome to the forums!

[KevinDAmery]

To add to Steve and Lisa's suggestions....

- On the Word import front, I lean more towards Steve's approach than Lisa's, simply because the cleaner and simpler the Word document is the fewer issues occur during the import. I'd especially make sure that you remove things like macros and that if there are fields in the Word documents convert them into plain text (i.e. if you have a date field, have Word change it from being a field to just a string of text that includes the appropriate date - I think you can do that globally by using Ctrl+A to select everything then Shift+F9 to resolve the fields, but I may be wrong on the second key combo.)

- For versioning, do you mean document versions or product versions? For document versions, I would use some sort of source control (Visual Source Safe, Toroise SVN, etc.) For product versions, what I do is create a Condition in Flare for each version I have to maintain, and whenever I learn of features that differ from one version to the other I apply the appropriate condition to the content pertaining to each version. Then in the output target I Exclude the conditions for versions other than the one that target pertains to. (E.g. my version 4.5 target excludes any content that has been conditioned as 4.0.) This is more streamlined than making a copy, because sometimes developers go and change something the applies to both versions (for example, during the development of 4.5 we also made some updates to the released version 4.0, and those changes were also going to be included in 4.5 - if I had copied the projects, I would have to make the same change in both sets of documentation, but because I kept them together I only had to make one change).

- When you say you have multiple writers, do you mean you have a team of writers but you're the only one with Flare? Or do you mean that some content is written by SMEs and you integrate their work into the document set? If the latter, I agree that X-Edit is a good idea. If the former... you really should try to get the other writers working in Flare too. Otherwise, as Steve says, it'll be a nightmare.

[dapellegrini]

Thanks for the replies so far!

Some clarifications:

1) We have one large piece of software for publishers - comprised of many modules (book publishing, magazine publishing, directory publishing, advertising, etc) and depending on the client you may need 1 manual, some of the manuals or ALL of the manuals. Currently our Word manuals are riddled with "see document XXX" for more information, etc. I am leaning toward making one large project, but not sure if this will be feasible. I have imported the first 2 Word documents, roughtly 1,000 pages and Flare is EXTREMELY slow processing moves, link updates etc. (for reference I am running a Dual Core 2, 2GB Ram, Vista Business Laptop). I wonder if a project comprised of 10,000 pages would just be to much overhead for the software and my computer?

2) I think I am clear on this - Thanks!

3) For versioning I mean software releases. We do 2 major releases a year and our Product Managers typically update their word manuals with new screenshots and updating wording etc. Using conditions may become too much overhead for this project, with lots of forks in the code. I am leaning toward sunsetting the prior versions documentation when the new version is released, but I guess I will have to play around with the options a bit on this.

4) Our product managers are typically responsibe for updating their user manuals in Word, which includes new topics, new screenshots, updated text, etc. This is not their full-time job however and having worked with flare for a few days I can tell you it would be an uphill battle trying to train them on it. Basically I am looking for a way, come new version release time, to send them some kind of an export file from Flare that they can update and send back. I would then review, revise and import into the new version of the help system.

Thanks again for all of your help getting going!

[forfear]

this is going to be an interesting post to follow.

12000 pages of Word to Flare?

yup that's a pretty common scenario for most i think.

[forfear]

you may wanna check out this work in progress by resident Madcap Framemaker/Print/Knowledge keeper guru Sharon Burton.


not completely relevant but you may wanna have a look at the guidelines by her at

http://madcapsoftware.files.wordpress.c ... raft45.pdf

[forfear]

also if this is of any help

http://forums.madcapsoftware.com/viewto ... nal#p30419
Print 101 Tips to Get You To Pro Design Status

this helps you

[MarinaMichaels]

And on a related note, if you don't already know XHTML and CSS, it could be well worth the time invested to learn about them.

1. Knowing XHTML is useful for when you want to edit using the internal text editor (which I do a lot to clean up artifacts from copying, pasting, and deleting when in the XML Editor). Surprisingly (to me), my general familiarity with XML is all I need. So far, anyway.

2. Knowing CSS is useful for when you want to customize the appearance of your output. I took an intense, in-deth class in CSS last year and, now that I am using Flare, am very thankful for everything I learned there.

[NorthEast]

Yep, I would say it's essential.
You need to know basic CSS and HTML just to use Flare, and when you want to make your own template you need to learn a whole lot more.

When we rolled out Flare and my template to the team I work with, the majority of questions were related to HTML and CSS rather than using Flare itself. Typically it was things like not knowing what all the tags meant (what's an ol, li, or span?), or how they were supposed to be structured (why can't I have a paragraph or drop-down inside a list?).

In this respect I can fully understand why people find Flare very hard to get to grips with.

[dapellegrini]

It would appear that I did well to postpone starting for a few weeks - seeing that Flare 4 was just released.

Thanks for all of the help so far. I am quite familiar with XHTML/CSS - have been hand coding websites for many years - though my last project was a couple of years ago now - a fully W3 compliant XHTML 1.1 Strict corporate website - for whom I am doing the documentation: http://www.msgl.com.

With my limited use of Flare I have thought on multiple occassions that it would almost be easier to write the code from scratch - as their interface is not immediately obvious to me. On the other hand, I find it extremely complex as a team tool, considering that I can't get most of our product managers to use Word correctly. I have yet to take a close look at the 4.0 release, hopefully there are some improvements.

[RamonS]

You may also take a look at X-Edit for those who may be too intimidated by the tons of stuff in Flare. It may still be more complicated than Word, but less so than Flare.