MadCap Software Forums

Hi,

I`m a technical author for a machinery startup. Currently I`m creating the operation manual for our first machine. I switched from saving the projects local to using git recently.
Soon I will have to create operation manuals for other machines based on the first manual.
Originally I intended to use one single project to store all manuals, as they will share a lot of content. But this wouldn`t allow me to branch the different operation manuals individually in git, if I get it right?
So I would have to create individual projects for every operation manual, and use Global Project linking to use my first documentation project as parent project?

Kind Regards
Tobias

It'll all depend on your specific use case and workflow - there's no right or wrong way to do it.
The benefit of having everything in one project is that you can share all of the content as much as you want without messing around with the extra layer of the global project. The benefit of multiple projects is that it can make it easier to organise large amounts of content that might be too inconvenient/slow to work with in a single project (as well as separating projects across different teams with shared branding, which is presumably not relevant in your case).

For branching, you absolutely could work on separate manuals in separate branches. You would just need to be careful about what changes you commit to which branch. For example, you might create a branch for ProductA/Jan23Release, where you would only work on the ProductA manual, and then a separate branch for ProductB. When each product goes live, you would merge those changes into the master branch.

I don't know your exact situation so take this with a grain of salt, but if I were you I'd stick with one project and avoid the unnecessary complication at this stage. Honestly I suspect that using extensive branching might be overkill for you - how often would you release new versions of the machinery that need to be kept in a separate feature branch until the documentation goes live? But maybe that's just my bias, we just push everything straight to master and only publish the documents when the feature is released.
[ETA: Just read your post (viewtopic.php?f=68&t=34029) in the Source Control channel - please disregard all assumptions I've made about how complex your documentation requirements could be!]

We take the single-project approach. So, we have five different models of one product line. We always create output from the Main branch, based on conditions and variables of each model's target. Since the models share a lot of the same content, we find this works well.

I'd also keep everything in one project for the time being. That's the simplest solution, and the simplest solutions are the easiest to maintain over time.

But I'd design the structure of the project such that, in future, the project could be split into a "global/corporate" project and individual "machine" projects. For example, I'd have a "corp" or "global" folder in the Content Explorer in which I'd put all the items that will be used universally, things like common stylesheets, common page layouts, corporate logos and such. I'd put each machine's content into its own folder. And potentially, I'd have a "shared" folder that contains content that is shared by the different machines. (I'm waffling on this one a bit, as I'm not sure if that material should actually be in the "global" folder.)

Even if you only ever have one project, organizing this way can help you (and your successor authors) readily find stuff in the project.

Nita's method is along the lines of what we use. While each model can share a lot of the same content, there are differences that need to be maintained and using folders like Synergy-HTX, Synergy-Neo, etc. makes content easy to find and include in a target.

We use a "Shared-Content" folder to hold things like Intended Use Statements, Warnings and Precautions and the like that are the same in each model, but specific text for a model is conditioned. Only content (topics) that are only for a specific model goes into the model folder.