Strategy for organizing large project, successive imports

This forum is for all Flare issues related to importing files or projects.
Post Reply
Curlyshell
Propeller Head
Posts: 65
Joined: Fri Mar 01, 2019 9:14 am

Strategy for organizing large project, successive imports

Post by Curlyshell »

I imported a large Word document, then learned that there was maybe three times as much material in "appendices," which actually all traveled together as one giant PDF.

So I need to import the new material and decide how to keep it. Here are my questions:
  • If some new section titles are identical to some existing titles—for example, "setup"—will they be overwritten or renamed? (In this 2014 post [viewtopic.php?f=5&t=18636], they were being overwritten...has that changed?) If so, then maybe I should wait until the authors finish sending me all 40+ appendices so I can merge them all in at once into a separate project?
  • The original took considerable pre-import prep and even more post-import work in Flare. If I import it straight into my existing project, some of the RegEx and other global search-and-replace might be messed up or at least made harder. So I'm motivated to import into a separate project and then merge the projects. Is that a good idea?
  • OTOH once this is all over the whole package will travel together evermore. Is there a way to do this as one project? Is there a reason not to?
  • My Flare work thus far has been pretty uncomplicated: CSS, HTML, a couple of targets. For structures such as master projects etc I'm afraid it's going to be more weeks of flailing around in the dark. I find MadCap's documentation to be aimed at an audience that understands all the concepts and just needs the particulars. Is it just me? Can someone recommend a book, author, etc. that does a better job of explaining?
Thanks so much!
"I'm a technical writer, not a developer," she said...
doloremipsum
Sr. Propeller Head
Posts: 290
Joined: Mon Aug 26, 2019 2:11 pm

Re: Strategy for organizing large project, successive import

Post by doloremipsum »

I don't have super specific answers, but here's my advice:
  • I usually find it most convenient to import a document into a fresh project, then move it into the full project. That way you can do some basic cleaning up and organising with the new files without changing anything about your existing project.
    The way I do it is import the topics into a fresh project, then move them into the folder structure that they will be in in the full project. For example, if your existing project has Topics > Document A, Document B, etc, you can put the new topics into a folder like Topics > Appendix 1. Make sure that the links are updated. Do the same for any images. Then use the Windows Explorer - not Flare - to copy the new topics, images and TOC into your existing project.
    This way you'll get all the new topics into your existing project with their TOC links and image links intact!
  • There's really no limit to the amount of stuff you can have in one project, so if the appendices are part of the document there's probably no reason to keep them in a different project. (My main project probably has 300 separate documents in it...) But if for example you had multiple projects which all needed to have these appendices available, you might want to start looking at global project linking.
  • Corollary to all of this is - make sure your topics have a useful file structure! Even just dividing them up into folders per document will make them easier to manage and prevent any overwriting issues.
in hoc foro dolorem ipsum amamus, consectimur, adipisci volumus.
Curlyshell
Propeller Head
Posts: 65
Joined: Fri Mar 01, 2019 9:14 am

Re: Strategy for organizing large project, successive import

Post by Curlyshell »

@doloremipsum, that is brilliant advice!

Let me add the following:

  • First, I have to distinguish what comes to me separately (groups of chapters) from what I want to keep separate (main manual vs. appendices). So in addition to following doloremipsum's excellent advice (A separate project for each import), I'll also be adding to the beginning of each header that generates a separate .htm file according to some plan. In this case, it will be the module name. So I'll have moduleX-setup, moduleX-how to use, moduleX-troubleshooting, etc. This will generate unique image names as well!!! In Flare I'll have to go back and remove "moduleX-" from the headers, which drives the left nav links. It's tedious, but that's why the good Lord invented audiobooks and find/replace.

    BTW I tried this trick (https://help.madcapsoftware.com/flare20 ... mports.htm) to force a different file name during import. The topic files were renamed as specified, but the image files were NOT! What up with that???
  • Still looking for your favorite Flare guide, other than this lifesaving forum...thanks!
"I'm a technical writer, not a developer," she said...
doloremipsum
Sr. Propeller Head
Posts: 290
Joined: Mon Aug 26, 2019 2:11 pm

Re: Strategy for organizing large project, successive import

Post by doloremipsum »

Curlyshell wrote:I'll also be adding to the beginning of each header that generates a separate .htm file according to some plan. In this case, it will be the module name. So I'll have moduleX-setup, moduleX-how to use, moduleX-troubleshooting, etc. This will generate unique image names as well!!! In Flare I'll have to go back and remove "moduleX-" from the headers, which drives the left nav links. It's tedious, but that's why the good Lord invented audiobooks and find/replace.
Glad you found it helpful! I'm not seeing this until after the weekend so it's probably too late - but there's no need at all to make the filenames unique! It's just like regular files on your computer: if the files are in different folders, then they are considered separate entities and can't overwrite each other.

For example, our hundreds of app notes are all in folders labelled /Content/Topics/Application Notes/AN-XXX. They often have equivalent topics such as Introduction, Prerequisites, Scenario, etc, but there's no risk of them getting crossed over (except on occasion when one person has several similar files open at the same time... let's say no technical risk). The graphics are organised in a similar way. I think you'll save a lot of time and effort by creating a logical folder structure instead of laboriously renaming topics and headings.
in hoc foro dolorem ipsum amamus, consectimur, adipisci volumus.
Curlyshell
Propeller Head
Posts: 65
Joined: Fri Mar 01, 2019 9:14 am

Re: Strategy for organizing large project, successive import

Post by Curlyshell »

Glad you found it helpful! I'm not seeing this until after the weekend so it's probably too late - but there's no need at all to make the filenames unique! It's just like regular files on your computer: if the files are in different folders, then they are considered separate entities and can't overwrite each other.

For example, our hundreds of app notes are all in folders labelled /Content/Topics/Application Notes/AN-XXX. They often have equivalent topics such as Introduction, Prerequisites, Scenario, etc, but there's no risk of them getting crossed over (except on occasion when one person has several similar files open at the same time... let's say no technical risk). The graphics are organised in a similar way. I think you'll save a lot of time and effort by creating a logical folder structure instead of laboriously renaming topics and headings.
Thanks again, and you're not too late! There's so much to do to these docs before I'm ready to import.

Chapters are trickling in, and I'm converting them in batches. Each separate import will go into its own folder, but that's just for the import process. There's no logical reason for the modules to be in 3 or 5 folders. Eventually, I should combine them.
"I'm a technical writer, not a developer," she said...
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Strategy for organizing large project, successive import

Post by ChoccieMuffin »

As for a good book, you could do a lot worse than look at what our very own Scott de Loach has written. I'm sure there's a link somewhere on the forums to his latest work?
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
trent the thief
Propellus Maximus
Posts: 608
Joined: Wed Feb 01, 2006 6:21 am
Location: Off in the dark....

Re: Strategy for organizing large project, successive import

Post by trent the thief »

Curlyshell wrote:@doloremipsum, that is brilliant advice!


...
In Flare I'll have to go back and remove "moduleX-" from the headers, which drives the left nav links. It's tedious, but that's why the good Lord invented audiobooks and find/replace.

...

[*]Still looking for your favorite Flare guide, other than this lifesaving forum...thanks![/list][/size]
Check out Bulk Rename at bulkrenameutility[dot]co.uk. It's been a real lifesaver for me when dealing with hundreds of renames. I've been using this package for close to 20 years,
Trent.

Certifiable.

Image

umm...
I meant MAD Certified.

Official Propeller Beanie Owner :-)

:flare: Are you on Flare's Slack channels? PM me for an invitation! :flare:
Post Reply