Student tech writer new to MadCap-New project best practices

[lacastle]

Alright, I'm about to get started with Flare. The Word file I've been building has picked up some eccentricities/bugs along the way and I'm wondering if I'd be best off:
a. typing everything into a Flare doc from scratch
b. stripping all of the formatting from the word doc., then importing into Flare and formatting on that end
c. importing the Word doc as is and hope for the best

It's only a 60-70 page document, so it wouldn't be the end of the world if I had to type everything in. I just want as few troubleshooting issues as possible.

i recommend b. or copy/paste from Word into Flare. i've found import works well for framemaker files, but not word as much.

[LTinker68]

a. typing everything into a Flare doc from scratch

I personally tend to go this route, for several reasons.

• I find it easier to organize the content into folders in the Content Explorer as I go instead of moving imported topics around.
• You generally don't want online users to have to do a lot of scrolling, so I tend to break up long topics into multiple topics and the Word doc isn't always set up for doing this separation doing the import process.
• The way things are laid out in print docs don't always translate well into online output or there needs to be some setup to get the content in a topic laid out so it'll work for single sourcing, and I find it easier to copy-and-paste a bit of content as I go instead of trying to rearrange a whole topic.
• Copying-and-pasting from Word to Flare is a good time to review the content to see if A) it's out-of-date and B) it needs to be modified slightly for online output and/or alternate blocks of text generated to account for various output situations.
• One good thing about Word is that it treats images well (shrinks them to fit the page without losing detail or going blurry) but you might need to modify images to adjust settings so they work well in both online and print outputs, and I don't think importing Word treats the images well, although that might have changed. Plus I like to organize the images as I go, too, and it's easier doing that as I work in the content.
• And a few other minor reasons.

That's just my preferred workflow. A lot of users import from Word (after cleaning up the doc first) -- I just prefer to copy-and-paste as I go.

[ccardimon]

You can always try out c., but there's one more alternative (at least):
d. Save the Word document as htm and open that one in Flare.

Cool! I never thought of trying that.

[seasonedrookie]

You have html tags already, maybe even with classes (I don't know whether Word writes that into a htm file), you wouldn't have to type it all in ... you might even get rid of the funny parts ...
"Saving under" in Word really doesn't take long, so just try it, open the file in a browser (don't look at it in Word) or even copy it into a Flare project and open it with Flare.
If it still looks like an effort, try making an RTF file out of it first, then make it into an htm file.
I remember tables causing some problems, but that was ages ago ...

Since all that doesn't really take long to try out, I would try that before typing all of it manually or reducing it to plain text (ASCII, txt, ...) and then assigning tags and classes for the whole, long document ...

Word doesn't give me an option to save as htm. Would it say "save as>htm" or something else? XML is a format save option, as well as RTF. Can you explain what saving as htm does as if you were explaining to someone who has no idea (because you are). Will it simply give me the text without the bugginess?

a. typing everything into a Flare doc from scratch

I personally tend to go this route, for several reasons.

• I find it easier to organize the content into folders in the Content Explorer as I go instead of moving imported topics around.
• You generally don't want online users to have to do a lot of scrolling, so I tend to break up long topics into multiple topics and the Word doc isn't always set up for doing this separation doing the import process.
• The way things are laid out in print docs don't always translate well into online output or there needs to be some setup to get the content in a topic laid out so it'll work for single sourcing, and I find it easier to copy-and-paste a bit of content as I go instead of trying to rearrange a whole topic.
• Copying-and-pasting from Word to Flare is a good time to review the content to see if A) it's out-of-date and B) it needs to be modified slightly for online output and/or alternate blocks of text generated to account for various output situations.
• One good thing about Word is that it treats images well (shrinks them to fit the page without losing detail or going blurry) but you might need to modify images to adjust settings so they work well in both online and print outputs, and I don't think importing Word treats the images well, although that might have changed. Plus I like to organize the images as I go, too, and it's easier doing that as I work in the content.
• And a few other minor reasons.

That's just my preferred workflow. A lot of users import from Word (after cleaning up the doc first) -- I just prefer to copy-and-paste as I go.

I like this route as well. Perhaps I can work out a combination of these practices, stripping the Word text of the formatting that is throwing it off, then copy/pasting into Flare section-by-section. Once I get the text imported, what is the proper way to format? Should I create a style sheet or a master page?

[seasonedrookie]

It also occurs to me that my employer bought the platinum maintenance package. Should I simply call MadCap customer service and have them walk me through the project set up? Is that a proper use of the service?

[SteveS]

If I am going to do a Word import I like to strip as much formatting out as possible, I'll even select all and format it as normal (even better use the little format erasor toll, it strips all formatting) before importing or cutting and pasting into Flare.

I'm a bit wary of Word HTML, back when I used Dreamweaver it had a cleanup Word HTM tool, so I'm not the only one.

I like to keep content seperate from presentation, which Word doesn't do well but HTML (Flare et al) does. So if I can get pure content from Word and then work on presentation (headings, emphasis etc) in Flare I am happy.

HTH

[LTinker68]

Once I get the text imported, what is the proper way to format? Should I create a style sheet or a master page?

That's apples and oranges. Stylesheets are for styling the appearance of the content. You can control the positioning of some elements via the stylesheet, but not all of that will be supported in all outputs.

The masterpage is for adding elements like breadcrumbs, a mini-TOC proxy if you want it, etc. It's kind of the frame around the content for online outputs. Page layouts do the same, but for print outputs. (Technically you can use masterpages for Word output, but I'd stick to page layouts for Word input.)

It also occurs to me that my employer bought the platinum maintenance package. Should I simply call MadCap customer service and have them walk me through the project set up? Is that a proper use of the service?

I think you'd do better by first watching the videos and reading some of the guides available from the help menu. That will get you started on learning and then you can post specific questions here.

[seasonedrookie]

The masterpage is for adding elements like breadcrumbs, a mini-TOC proxy if you want it, etc. It's kind of the frame around the content for online outputs. Page layouts do the same, but for print outputs. (Technically you can use masterpages for Word output, but I'd stick to page layouts for Word input.)

Sorry, you really have to spell things out for me. So after I get the content into Flare, what should I use to format/stylize the content, e.g. font size/type, heading levels, etc? Are you saying to use Page Layouts? Don't use CSS or Masterpage yet? The ability to tailor content at so many different levels is what is overwhelming about Flare for me. I just need one, simple way to achieve the desired results, that won't cause me problems down the line. Thanks everybody for hanging in there and explaining this stuff to me.

[seasonedrookie]

As I get further along in my Flare handbook, I'm starting to get an idea of how to set up and work on projects. I think consulting the forum 100x, then thinking about it 100x, then reading about it over and over, is beginning to make the steps/practices stick in my head a little better...like anything else, I suppose.

[NorthEast]

Regarding getting the Word documents import into Flare, I would try the Word import first, since it is pretty quick to see the results. It gives you a number of options such as how to split the document into topics, and allows you preserve the styles from the Word document or map the styles to your own stylesheet. Unless you've been very careful in how you use styles in Word, preserving the styles will probably give you a few extra styles that you'll need to tidy up (e.g. several variants of the same style). Mapping styles to your own stylesheet will make things much tidier from the start, but of course you would need to create this stylesheet first.

Although it is possible to save documents as a web page (htm) from Word (using Save as > Other Formats), I really wouldn't advise doing this as a way to import content. The HTML code generated by Word is pretty messy and would require a large amount of editing and reformatting to clean it up for use in Flare; it'd be quicker to copy and paste the content and format it from scratch.

[LTinker68]

Sorry, you really have to spell things out for me.

The stylesheet is for setting the font (family), font size, color, bold/not bold, bullet styles, if you want an image next to a paragraph for a note icon, etc. If you go to almost any website, you're seeing some effect of styles on content; it's recommended that the styles be contained in a stylesheet file as opposed to being embedded in each web page so all the web pages in a website use the same styles and therefore have a consistent appearance.

The masterpage and page layout are Flare features that you don't see directly in the output, but you see their effects. If you want your online output to have a breadcrumb, you add a breadcrumbProxy to a masterpage. In the authoring environment, the masterpage is separate from the topic, but when the online output is generated, they're merged into a single html file. Likewise, the elements of the page layout are merged with the content from a topic to generate a page in the print output.

[crdmerge]

The legacy filth that builds up in a Word file (usually multiple writers with varying levels of expertise) gets piled up; as a selection is changed, the new style is often added to, instead of replacing, the old style. The result? Dueling spans that are nearly impossible to remove in the XML Editor, and painfully possible in the Text Editor. The answer? The nuclear option: copy the content from the WYSIWYG mode, paste it into Notepad, then copy that and paste it into Flare. Then assign styles, create lists, create tables, etc. It's way less grief than any other option provided here, so far. Then, of course, if you have Word original content that was saved as HTML, imported to RoboHelp, which was then converted to Flare...it gets pretty ugly, folks!

Here's a mild version of what you can run into:

Code: Select all

...select <span style="font-style: italic;" xmlns="http://www.w3.org/1999/xhtml"><span style="font-style: normal;" xmlns="http://www.w3.org/1999/xhtml"><span style="font-style: normal; font-weight: bold;" xmlns="http://www.w3.org/1999/xhtml">by Executed Broker</span></span></span><br xmlns="http://www.w3.org/1999/xhtml" /><span style="font-style: normal;" xmlns="http://www.w3.org/1999/xhtml"> in the...

Good luck,
Leon

[seasonedrookie]

I think my best shot at learning my way around Flare is to create the project from scratch, at least to start.

So far, I've:

• Opened a new Flare project

• Under Project Organizer, I opened TOCs > Master(Master)

• Pressed "Create new topic and link to it" button (I did this for every topic that is a Heading 1 in my Word document)

I entered the Heading 1 titles in the box labeled "File Name." I didn't mess with the advanced options here.

My questions now are:

1. I have titles that require slashes "/" in the title, but the File Name box won't allow for slashes. In this case I assume I would use the advanced boxes. Which advanced box option would I use to include the title that I want to appear in the printed document (the title that will include the slashes "/")?..."1st Heading" or "Title." Will I have to make any selections so the title with the slashes is used instead of the File Name text?

2. Now that I have my level 1 headings in the TOC, do I follow the same pattern for my subheadings or do I go into each topic individually and make files for the subheadings?

[LTinker68]

1. I have titles that require slashes "/" in the title, but the File Name box won't allow for slashes.

It doesn't allow slashes in the filename, but it's fine in the heading. When you're in the Add New Topic screen, in the File Name field, enter a filename for the topic, without the .htm and I recommend not using spaces. Use camelcase or underscores or dashes. So the filename would be something like scrConfigMain. In the 1st Heading field, type the text you want to appear as the first heading in the topic. When you drag this topic to the TOC to add it to the TOC, this value will be used for the text of the TOC entry. This is the field where you can insert the slash mark if you want. So the 1st Heading field could be set to Configure/Main Screen. You can put something in the Title field, which will end up in <title>...</title> tags inside the topic. I tend not to use that field and I just leave it blank.

2. Now that I have my level 1 headings in the TOC, do I follow the same pattern for my subheadings or do I go into each topic individually and make files for the subheadings?

That's up to you. I tend to use h1 for the first heading in every topic, which works best for online output, IMHO. For my print output, I enable the "use TOC depth..." option, which will convert an h1 to h2 if the topic is a child of another topic (book) in the TOC. I then have my h2 styled as I want for that situation.

[seasonedrookie]

Thanks! I know this is elementary, but I can't figure out how to get the options that were available in the Add New Topic popup. How do I make the adjustments that you mentioned to the File Name and 1st Heading boxes after the topics have been created?

[seasonedrookie]

2. Now that I have my level 1 headings in the TOC, do I follow the same pattern for my subheadings or do I go into each topic individually and make files for the subheadings?

That's up to you. I tend to use h1 for the first heading in every topic, which works best for online output, IMHO. For my print output, I enable the "use TOC depth..." option, which will convert an h1 to h2 if the topic is a child of another topic (book) in the TOC. I then have my h2 styled as I want for that situation.

Thank you for your help. I'm not quite ready for anything to be up to me. I'm still thinking of this doc in terms of a Word doc. What is one good way to make a section title followed by subhead titles to be included in the section? I'm having trouble seeing the bigger picture beyond that. I just want to get my topics all set up so I can insert text.

[LTinker68]

The file name you just modify in the Content Explorer like you would in Windows Explorer (slow double-click or left-click then F2).

If you didn't put anything in the 1st Heading or Title fields, then the only thing you need to do for the first heading is actually put one in the topic, which Flare does automatically. So if the 1st Heading field is blank when you click Ok in the Add New Topic screen, then Flare will automatically insert an h1 tag whose content is the same as the file name. So a filename of scrConfigMain will result in a first heading of scrConfigMain. You can just change that text and you're fine. If you created the topic from the TOC, then the TOC entry will say scrConfigMain, in which case you rename it by a slow double-click or by opening its Properties screen and manually changing its value.

If you entered something in the Title field of the Add New Topic screen and don't want it, then you'll want to open the topic in the Internal Text Editor and manually delete the <title>...</title> block. Or you could open the topic's Properties screen and delete the text in the Topic Title field, but that leaves <title></title> in the topic and I'm not sure if that causes problems later or not with search, favorites, index, etc. (Like I said, I always leave that field blank.)

Regarding the h1 and h2... You really need to read the Printed Output Guide available under Help > Guides.

[seasonedrookie]

The file name you just modify in the Content Explorer like you would in Windows Explorer (slow double-click or left-click then F2).

Did you suggest deleting the .htm here? If yes, why?

[LTinker68]

No, I said not to put it in the File Name field of the Add New Topic screen, since Flare adds it automatically, although I didn't mention that.

[seasonedrookie]

Regarding the h1 and h2... You really need to read the Printed Output Guide available under Help > Guides.

Good morning MadCap Forums,

It's a new day working with Flare and of course that brings up some new questions. I read the Printed Output Guide as you suggested. I didn't see anything specifically referencing heading styles, but from what I can tell, these are things done after getting all of the project content into Flare.

I created subfolders to house my topics. This helped me wrap my brain around things a little bit better, but I still don't understand the alphabetical ordering of topics. I can understand that they are easier to locate that way, but it doesn't help my though process as far as getting the content in the right place. At what point will I be able to arrange topics into the order that they will need to be in for the manual I am creating?

I'm also wondering if I should only be concerned with getting unformatted content into the document at this point. Will I create my bulleted lists, notes, etc. after I get all of my text in?

All the Best,

Ryan

[lacastle]

At what point will I be able to arrange topics into the order that they will need to be in for the manual I am creating?

This will come when you create a TOC - http://webhelp.madcapsoftware.com/flare ... ntents.htm

I'm also wondering if I should only be concerned with getting unformatted content into the document at this point. Will I create my bulleted lists, notes, etc. after I get all of my text in?

I find it easier to put unformatted text into flare (if importing or copy/pasting) because then i can edit it as i go and decide how i want it to look. are you writing this content from scratch (in the word doc) or do you have a previously-formatted doc to work off of? if the word/first version is formatted, i like to copy/paste into flare but look back at the word original to see where the original author had specific formatting (then decide if i like the original or if i want to make changes). also, you will have to clean up some of the styles coming over from word anyway if you don't already have styles set up in flare to match up.

i recommend reading the Import flare help if you decide to go that way - http://webhelp.madcapsoftware.com/flare ... uments.htm

I didn't see anything specifically referencing heading styles

did you see this in the flare help about headings? - http://webhelp.madcapsoftware.com/flare ... amples.htm

[i-tietz]

I can understand that they are easier to locate that way, but it doesn't help my though process as far as getting the content in the right place. At what point will I be able to arrange topics into the order that they will need to be in for the manual I am creating?

Trick: Rename the topics. E.g.:
first.htm --> 1_first.htm
second.htm --> 2_second.htm
third.htm --> 3_third.htm
fourth.htm --> 4_fourth.htm
...
If you have more than 9 topics in a folder, add a zero at the beginning, e.g. 01_first.htm

I'm also wondering if I should only be concerned with getting unformatted content into the document at this point. Will I create my bulleted lists, notes, etc. after I get all of my text in?

This sounds like you need to look at some of the beginner's PDFs and movies ... we cannot explain the handling of Flare from scratch here in the forums.

[seasonedrookie]

Thanks everyone. Things are going along pretty smoothly, except... Flare has crashed two times and it's not even noon yet. I get the error message:
"MadCap Flare has stopped working
A problem has caused the program to stop working correctly. WIndows will close the program and notify you if a solution is available."

What's up with that? This happened at times when Flare was working fine and all I was doing was typing text into topics. I'm working with only one topic opened at a time. Luckily I've only lost minimal amounts of text, but having to restart isn't fun. I hope this isn't a taste of what's to come.

[lacastle]

are you working on a local copy of your files or through a network? local is faster, by the way, especially once you get a lot of topics.
i had a problem years ago with the 'failure/shout down' issue when i was copying and pasting tables into flare, but i think that issue was fixed.

[seasonedrookie]

are you working on a local copy of your files or through a network? local is faster, by the way, especially once you get a lot of topics.
i had a problem years ago with the 'failure/shout down' issue when i was copying and pasting tables into flare, but i think that issue was fixed.

I am working on a local copy, saving frequently there, and periodically I will save to the server by going to file>zip>zip project.