Why Go to Multiple Projects? - First Impressions

[jbarwick]

I have posted this question before in the hopes that someone would give me "the good" and "the bad" about using Flare with multiple projects.

I didn't get much response. The responses I got though were helpful. Thank you.

Most of the responses were "Never tried it". Then, the conversation terns into a lot of unknowns about what happens with the TOC.

Well, today I decided (actually last night) to split my project into multiple projects and to heck with issues regarding the master TOC. Why?

Size...

It was taking over 45 minutes to generate the project as all 26 books were in one big project. This made it incredibly tedious to publish the project.

So ... split it.

Here are my first impressions and what I did:

1) Create 4 new projects (just to see how the defaults make things look)
2) In the master project (project 4) link in a TOC projects book1, book2, book3
3) Generate

Impressions:

1) WOW! Very very interesting. Now each book will generate by itself and not be regenerated unless necessary! I'm ready to split my project!
2) Master TOC. Remember how you can point an entry in a TOC to another TOC? And you can't specify a topic to show? Well, it appears at first glance that the imported projects are adhering to the "default topic" rules for a TOC/Book. Therefore, when I click on a Book in the master TOC (project 4) it is showing me the default topic for the project TOC! This I couldn't do with linked TOC's! (I hope I got this right...)...anyway...

These are just my first impressions and observations. I though I'd share as others that commented on my previous posts might think them interesting.
I'll post final impressions when I finish splitting all 26 books into Sub-Projects.

[doc_guy]

I suppose it is too late, but you made a back up of your project, just-in-case, right?

Good luck!!

[jbarwick]

Second Impressions.
It took a few days, but I have finished creating my 20+ individual projects and a master project.

Second impressions...

Continues to be interesting, and the master project copies ALL projects into the "/project/Subsystems/" folder and the master project is in "/project/Content"

The output looks good. I was mistaken about the TOC loading a topic on the linked project (sorry folks...acts just like a linked TOC). The Master TOC and the Master Index looks good and combined across all projects.

However...inserting hyperlinks across projects...there doesn't seem to be a whay to do this. I am growing more concerned. Now I'm wondering if I must use CSH to insert hyperlinks in the projects that cross projects.

HELP! Any clues? I don't have many links. Basically, 99.9% of the links that cross projects only are intended to go the the subproject main index and TOC...or..behave exactly like a CSH call.

I haven't tried the CSH yet...this is my only last hope. Will keep you posted.

[jbarwick]

I suppose it is too late, but you made a back up of your project, just-in-case, right?

Good luck!!

OOOOOh! Yes!!! 2 on two computers actually. Just in case I mess one up.

And, it' my Subversion Revision 303 that contains the "pre split" version.

[jbarwick]

Since there doesn't seem to be a "helper dialog" for entering hyperlinks into merged projecs (this seems like a HUGE OVERSIGHT from Madcap)...I manually entered them.

In the hyperlink dialog, I entered

../Subsystems/<output name from target 1>/Content/Index.htm
../Subsystems/<output name from target 2>/Content/Index.htm
.
.
.
../Subsystems/<output name from target 26>/Content/Index.htm

After builing, clicking on the hyperlinks do indeed open the TOC to the correct section and displays the file.

[jbarwick]

Next Impressions...

Limitations...

The biggest issue right now is Hyperlinks and Cross-Reference.

My idea WAS going to be that I would have a project for each book (or "Volume"). Then I was going to hyperlink across my projects.

The Good:
* My compile time has moved from 45 minutes to 5 minutes (about). This is due to the fact that it is not compiling every "book" every time. They are "up-to-date"...cool!
* Organization. My staff cannot handle the fact that the project contained multiple books. A person was working on "one book" and got totally confused that there were 60 or 80 "targets" for builds. Plus, they were constantly having to navigate around all the other books. Now everything appears more organized and initial feedback from my staff is positive.
* The corporate stylesheet is in the "master" project. Each book has its own stylesheet in the "Resources" folder and that stylesheet performs an @import of the corporate stylesheet. This keeps my staff's itchy fingers out of he stylesheet unless they make an override. And they must have a good reason! (this doesn't really have anything to do with multiple projects...but performing this project split gave me this idea. The stylesheet is pre-published on our documentation website). Don't really know yet how this will effect BOOK/PDF creation out to FrameMaker (no, I haven't tried internal Flare4.1 PDF yet)
* Unified TOC
* Unified Index
* Unified Search
* If I happen to change the stylesheet too dramatically for a particular book (to keep history), then I can have better stylesheet/project segregation.
* I can build ALL projects with a single click! (Rebuild takes 45 minutes)

The Bad:
* There does not seem to be "project group". A project group would allow Flare to know what projects will be in the "Subsystems" folders and allow for hyperlink creation. But Madcap didn't think of this. Yes, MadCap, you can have this idea for free....
* There is no way to add "Cross-Reference" links across projects. Again, a project group would solve this problem.
* There is no way to add (except manually) hyperlinks across projects. Further, these are "external" hyperlinks and Flare 4.1 reports them as "errors" during compile. They are not errors. Warnings are fine...but errors?
* Although there was a blurb about "sharing content across projects" somewhere in MadCap marketing...this doesn't seem to be possible...still searching.
* Flare compile process needs to be more "makefile" based and not recreate OBJECT files (output folder) if the project in the "Target" subsystems folder is "up-to-date". Re-Copying the "Output" from the merged project into the Subsystems folder of the Master Project every time the master is built is a waste of time. No, really...this takes a LONG time. Especially on an output folder with 5000+ files/folders. (I have one really big book)

Well.. I'm not really keeping a formal list of good/bad...so I might update this post as I progress....And...if there is a way to do cross project cross-reference and hyperlinks...Let me know! I'll amend this post!

So far everything is "o.k." I have not removed all "Cross-References" across books yet...so I'm sure to have some broken links. But it's almost exactly like my single project right now. So, it's basically good.

More to come I'm sure....

[NorthEast]

I've been down a similar road to this. We have quite a large project with about 2000 topics, which were originally imported from 12 different guides (FrameMaker/WebWorks).

I tried out the project merging, and whilst the feature does what is says it will do, I found that setting links between projects extremely awkward and problematic. We wanted to add quite a lot of links/xrefs between the projects to make them more integrated, but setting up links is quite difficult.
Firstly, you can't browse for the topic; so you have to check what the topic filename and path is in your other project, and then enter it using quite a long path name. I wouldn't fancy doing 100s of those.
Secondly, there's no way to check for broken links, which could be a real testing and maintenance headache. Say somebody renames or deletes a topic that was linked to from another project, you won't know about it. Also, given you have to type in links by hand, typos will be quite likely.

So, for me, project merging wasn't an option because of the problems with links. If you only need very few links between your projects though, it could be a more viable option.

Then I tried putting all my content in a single combined project. My initial concern was how manageable a large project would be, but we've been using it for 6 months now and it works out very well. We use source control (VSS), so there's no issues with multiple authors working on the same project.

One tip if you are worried about build times - the solution we've used is to make partial builds. The project topics are in 12 sections, and each section is in a separate folder that has a condition tag applied (with the section name). When we are writing the help, we typically only want to test out a handful of new topics, so we can use the conditional tags in the target to build only the one or two sections we've been working on. Each author has their own target which they use for their own test builds, and we have one target that builds the complete help. Typically a partial build might take 2-3mins, versus the 20mins of a complete build.

[alaltenburg]

Hello. I currently have 25 seperate flare projects. The good news is that you CAN hyperlink between projects.

The only catch is that you have to have all the projects within the same folder when they are published. I use separate projects because the software is a work in progress and when I debug specific chapters, I do not want to have to publish all 25 chapters. This allows me to publish only the chapter I want to.

I found the easiest way to hyperlink between chapters is to go to the one already published and right click in the page I want to hyperlink to. Then go to properties. This gives the address that I need to link to. Then in your current project, click on hyperlink and make sure you select external topic. Just past the address in there and you are good to go. The flare preview window will not work, but it will work after published.

http://kb.madcapsoftware.com/Content/Fl ... _a_CHM.htm

It took me some time to figure it out, but now that I have it, it's really easy. Hope this helps!

Andrea

[doc_guy]

For what it is worth, when MC marketing talks about sharing content across projects, I believe they are talking about global project lining where you can have a master project and you can import content from that master project into child projects.

That is the only way I know of to share content across projects. But it doesn't help solve the problems you're talking about.

[ktbCA57]

I'm curious: are these multiple projects all used in the same application? If so, how did the developers go about integrating them into the software?

Thanks,

kb

[NickC]

jBarwick wrote :

There does not seem to be "project group". A project group would allow Flare to know what projects will be in the "Subsystems" folders and allow for hyperlink creation. But Madcap didn't think of this. Yes, MadCap, you can have this idea for free....

This is something that has been requested by myself and others and would be extremely useful for global project management. You can add a feature request https://www.madcapsoftware.com/bugs/submit.aspx. And more generally, the possibility to add or modify project folders (target, in particular).

Not sure this enhancement would allow you to add Xrefs between different projects but anything that simplifies hyperlinking and Xrefs would also be welcome. I agree with you and Dave Lee that manually adding hyperlinks between projects works but is error prone. I have a master project with links to 20 sub projects (all in the same subsystems folder of course) with a total of around 800 topic files. Being able to better manage hyperlinks - and feel confident to use more of them between projects would greatly enhance our doc. Another area for improvement would be how to manage hyperlinks for different formats. Hyperlinks to a compiled project are OK but if you compile separate PDFs for each sub project, you need the hyperlink to be conditioned out or some sort of option which allows you to convert the live link to a text string (eg: "See PDF XXX for more details"). Maybe someone has a neat technique/workaround for this?

Also for lengthy builds of big single or multiple projects, I recommend the madbuild command line programme. I schedule builds overnight. Works a treat!