Multiple projects versus Multiple TOCs

[Mathew Weaver]

We currently have five main projects, plus three additional projects that are shared/embedded into the main projects. This has been working fine because we are using passive version control via Git, so all of the projects are in the same Git repository (so the repository maintains the correct folder structure). We are planning to switch to TFS for version control. As noted here**, "each TFS project in a collection can store one and only one Help+Manual project." Since each project must exist separately in TFS, it may be confusing to get all of the projects downloaded to the correct local folder structure to allow the sharing/embedding to work properly.

We just learned about multiple TOCs*** within the same project. By combining all of our existing projects into one project, then using multiple TOCs for publishing, we could keep everything in a single TFS project and avoid the confusion of downloading the projects into the right folder structure. It would also make it easier because synchronize with TFS would automatically synchronize everything (instead of doing it one project at a time).

One downside to multiple TOCs in a larger project is that everyone must download the entire project to edit any content. However, the upside is that it may reduce duplication of content - because everyone will be working in the same project so they will easily see what content already exists.

Are there any other advantages or disadvantages of using multiple TOCs in a single project versus separate individual projects?

Is there an official recommendation for one approach versus the other?


** http://www.helpandmanual.com/help/hm_ad ... nstall.htm
*** http://www.helpandmanual.com/help/hm_ad ... s_tocs.htm

[Tim Green]

Hi Matthew,

If you have not yet acquired TF'S and still have the ability to choose which version control system you want to use, we urge you to use SVN instead. It is superior to TFS in every conceivable way, and massively easier to manage and understand. It also integrates with third-party programs like Help+Manual much, much better. If you are worried about Visual Studio integration, VisualSVN is available for this and works very well. Choosing SVN over TFS will save you a lot of hair-tearing and pain.

Are there any other advantages or disadvantages of using multiple TOCs in a single project versus separate individual projects?

This really depends on the project. If the differences are great enough so that each TOC is really a separate project, then I would recommend using separate projects. But if they are really more or less varians of the same project then multiple TOCs can be a more efficient solution.

It's also important to understand the difference between the main TOC and the secondary TOCs. The main TOC (the one at the top) always includes all the topics in the project, even if you remove TOC entries from it. It represents the "entire" project. The secondary TOCs are the ones that exclude topics automatically when you remove TOC entries from them. See here for details:

http://www.helpandmanual.com/help/index ... s_tocs.htm

[julio]

We are Microsoft Gold Partners and use TFS and Visual Studio to host all our documentation projects. Unfortunately, H&M integration with TFS requires a single documentation project (.hmxp) per TFS project, which is not our case. We have several documentation projects inside each TFS project and the trouble to fit that limitation would be tremendous.