Structuring a Multi-Author Multi-Phase Multi-Output Project

[homerchristensen]

Hi There... First post in the forums. Looked through and found somewhat similar topics but not close enough to help me solve my dilemma. I appreciate any help and guidance.... and am happy to elaborate more offline. Contact me at rchristensen [at] drc [dot] com.

We're a team of three writers on a multiple-year multi-phase doc and training project for a behemoth of a software app for a state agency. No chance of using source-safe software. We three author in Flare 6 and we may add one or two writers who will have to use Word 2007. We author on our laptops and I have secured a networked desktop machine that will run the builds. (Our laptops have a whopping 1 MB RAM.) The desktop is speedier, but the connection speed prevents us from working off it in real time.

We’ve completed our topic analysis for the first release (5 modules + Overview) which includes several hundred topics and a thousand+ graphics. The second release will be much larger, and the third, fourth, and fifth releases will continue to add hundreds of topics each. So it quickly can get big and gnarly. We are on the hook for delivering a WebHelp system and User Guide (PDF) for each release.

We can pretty much split the work so that we each author complete modules. That should reduce the stepping on toes and overwriting another’s work. Plus, each module has its own set of SMEs and reviewers, so we can publish review drafts independently.

I want to ensure we use the same common files (CSS, page layouts, status tags, conditionals, etc.) and that each release includes the previous release contents.
When I tried linking the common project to the module file, I found that I couldn’t select a style from our stylesheet. Only the default.css styles appeared in the list. Is this normal?

So then I thought I might create:

• A modx project for each mod that contains only topics and the approved CSS. We would do our authoring in these projects.
• A common project for the common files (css, page layouts, etc.)
• A master project that would link to the common files and the topics of all mod projects, so that we could generate a composite help system/document of all topics for the app. Each release we would simply add links to the mods in that release.
• A print_modx project for each module that would link to the common and module topic files. This would be used primarily for testing and preparing review drafts of a single module.

This seems like it might be a good solution.

What I don’t know is how does the project linking work with relationship tables, snippets, indexing, and other cross-module connections?

Can (or should) the snippets live in the common project? And if we want to create one that can be used by anyone, do we have to create it in the common files, re-import into each project, and then insert the snippet into the topic?

Do we specify the relationship table for each module and is it possible to have cross-project relationships?

Is there an order of precedence… for example, do the defaults chosen in the master override those in any child project?

What else should I be considering or aware of?

Or is there simply a much better, more elegant solution that you fine people came up with?

Thanks in advance--
homer

[NorthEast]

So then I thought I might create:
* A modx project for each mod that contains only topics and the approved CSS. We would do our authoring in these projects.
* A common project for the common files (css, page layouts, etc.)
* A master project that would link to the common files and the topics of all mod projects, so that we could generate a composite help system/document of all topics for the app. Each release we would simply add links to the mods in that release.
* A print_modx project for each module that would link to the common and module topic files. This would be used primarily for testing and preparing review drafts of a single module.

That looks sound; a few comments:

(1) Do you need to include links between topics in the separate modules?
For example, if someone is working on the mod1 project, then they can't add a link/x-ref to a topic in the mod2 project; they'd need to have the topics from mod2 available in the mod1 project.
So if you do need cross-module links, one solution may be to use project imports to import the topics from all the other modules. So this would be a bit like how you'd set up your master project; e.g. mod1 imports topics from mod2-mod5. This does mean setting up the imports for the master project is slightly more complicated, but I can think of a few ideas if you go down that path.

2) Using a common project for your 'template' (stylesheets, layouts, etc.) is a good idea, it means you only need to change these once and they'll be picked-up by all your separate projects. I'm assuming you'd also import the common project in your modx projects? (as well as the master)

3) I'm not sure what's different about a print_modx project to a modx project.

Can (or should) the snippets live in the common project? And if we want to create one that can be used by anyone, do we have to create it in the common files, re-import into each project, and then insert the snippet into the topic?

Only those snippets that are actually 'common' and will be used in all the modules (and must be the same). If the snippet is only used in a single module, then you don't need it in the common project. Obviously the modx project imports you set up in your master project need to include snippet files.

Do we specify the relationship table for each module and is it possible to have cross-project relationships?

Firstly, I don't use relationship tables - so check this out. I'd assume that to select the topics for a relationship table, then they have to be available in the current project you're working on. So this should be ok if you set them up in the master project, but in your modx projects then you may have the same issue I described above with cross-module linking, and so need to import topics from your other modules.

When I tried linking the common project to the module file, I found that I couldn’t select a style from our stylesheet. Only the default.css styles appeared in the list. Is this normal?

If you have more than one stylesheet in your project, check that you don't have the master stylesheet set to use the wrong one. You can set a master stylesheet in two places - the project properties, and the target properties.

Is there an order of precedence… for example, do the defaults chosen in the master override those in any child project?

An order of precedence or defaults for what?
Generally speaking, I don't tend to leave anything set as 'default'; e.g. in my targets I don't leave my master TOC, page layouts, or stylesheet medium set to (default), simply because I don't know what might be used.
The primary TOC and target you can set in a project is just saved locally, i.e. they're just saved for your account on your PC.

We're a team of three writers on a multiple-year multi-phase doc and training project for a behemoth of a software app for a state agency. No chance of using source-safe software. We three author in Flare 6 and we may add one or two writers who will have to use Word 2007. We author on our laptops and I have secured a networked desktop machine that will run the builds. (Our laptops have a whopping 1 MB RAM.)

Can you request source control, better PCs, or Flare licences for the additional authors? These may hinder your efficiency longer-term, given the potential size of the job.
It just seems like you're being asked to dig a hole with a spoon; it's possible, but it's more cost and time efficient to use a shovel. Anyway, I hope the laptops have 1GB and not 1MB!

[homerchristensen]

Thank you for your thoughtful response, Dave.

My print_modx projects were primarily designed simply to add the draft page layouts and their associated revision info and review instruction topics, which I can exclude from the master project with a conditional flag. So I won't need those. That'll save time and effort.
I was also concerned with the master project getting crowded up with TOCs and multiple copies of the CSS file, but after reading and experimenting more I feel comfortable in setting up the conditional flags or exclude rules to keep the import clean.

Also, most of the cross-referencing of topics between mods will likely be between the overview/basic navigation/common tasks module (mod1) and the others, so it sounds like it makes sense to import those topics into the modx projects. When we do the draft print exports, the page references will likely throw errors (since the mod1 topics won't be in the TOC), but we can work around that.

Is there an order of precedence… for example, do the defaults chosen in the master override those in any child project?

By "defaults" I meant "settings" really. So if you mistakenly chose a competing CSS, TOC, or Page Layout in your Master Project's project and target properties, which would take precedence (I'm guessing now that the target would, since that would be the point of action) and would they supercede any settings in the child projects?

Would we need to set up a TOC exclusively for the master project within each child project so that the page numbering, etc., would not reset to 1 for each module's first topic in the printed targets? And this TOC would also not include the front matter and appendices that are added for the review of each draft.

Is a rule in working with linked projects that one edits a linked topic only in the original project? It didn't appear to allow one to update a linked topic. I saw only the option to break the link or cancel the edit when I tried to modify a linked topic. For example, could you create your index in the master by inserting index tags within linked topics?

Do the index and glossary proxies find all entries within all child projects? For example, if the master project contains the TOC, index, and glossary proxy topics, will it consolidate all entries from the linked projects? Seems like it might make more sense to create and maintain the glossary in the master, but it is also nice to do so at point of use of the term.

Is there any issue with CSH files (either the alias or the map file) that comes into play when linking projects?

---

This also begs the question for me: Is there a location holding white-papers or where writers document what they did or how they structured their project to meet their particular needs? If so, I will certainly add mine with any lessons learned as we go along.

-homer-

[NorthEast]

I was also concerned with the master project getting crowded up with TOCs and multiple copies of the CSS file, but after reading and experimenting more I feel comfortable in setting up the conditional flags or exclude rules to keep the import clean.

Yeah, in the master project, only import what you need from each module - like topics, images and TOCs; but not the things that are common between all your modules, like stylesheets or page layouts, which you would import from the common project.

One other tip would be to create a folder in each module project to store the topics, e.g. in the mod1 project, keep the topics in a folder Content\mod1. So when you import the modules into the master project, the topics for each module will be in separate folders. It makes organising things a bit easier, and any relative paths to files imported from your common project (e.g. stylesheet) will remain the same.

By "defaults" I meant "settings" really. So if you mistakenly chose a competing CSS, TOC, or Page Layout in your Master Project's project and target properties, which would take precedence (I'm guessing now that the target would, since that would be the point of action) and would they supercede any settings in the child projects?

For the master TOC, page layout and stylesheet settings; the settings in the target take precedence over the project settings.

With regards to importing, there's not really any potential for these settings to conflict. If you think about it, there's no connection between the project settings in the master and child projects (i.e. you're not importing any project settings). You can't have conflicting properties for targets, settings for one target file (imported or not) can't affect another target.

But like I said, if you set up targets so nothing is left to (default), then you won't get any inconsistent results.

Is a rule in working with linked projects that one edits a linked topic only in the original project? It didn't appear to allow one to update a linked topic. I saw only the option to break the link or cancel the edit when I tried to modify a linked topic. For example, could you create your index in the master by inserting index tags within linked topics?

Yes - for a topic that you want to be linked. The link is one-way, so you can't edit a topic in the master project and have it update in the child project. You'd only break that link if you want the topic to be different in the master to the child - i.e. not actually linked.

Would we need to set up a TOC exclusively for the master project within each child project so that the page numbering, etc., would not reset to 1 for each module's first topic in the printed targets? And this TOC would also not include the front matter and appendices that are added for the review of each draft.

In your module project TOCs, I would suggest applying a condition to the front matter sections. Then in your master project, just exclude that condition in the target so they don't appear.
The page numbering should be fine, as long as you don't explicitly reset the page number anywhere in your module TOCs.

Do the index and glossary proxies find all entries within all child projects? For example, if the master project contains the TOC, index, and glossary proxy topics, will it consolidate all entries from the linked projects? Seems like it might make more sense to create and maintain the glossary in the master, but it is also nice to do so at point of use of the term.

Yes, as the master project contains all of the topics, it will include all the index entries from those topics.

The glossary will reflect the glossary files you have in your master project. So if you have separate (i.e. different) glossary files for each module, then you need to import these into the master. If you just have one glossary file with common terms, it may be sensible to keep that in the common project; then it can be imported and used by each module project (if you want glossary links in the modules) and the master project.

Is there any issue with CSH files (either the alias or the map file) that comes into play when linking projects?

That's a tricky one actually. Since your master target (any target) can only use a single alias file, if you had a separate alias file in each child project, then although you can import these into the master you can't actually merge the entries together. You could manual copy and paste entries using a text editor, but that's hardly ideal. I think you'd have to set up the alias file in the master project only.

[homerchristensen]

Excellent feedback. Thank you!