Architecture for Machinery

[Shredder]

Hi folks,

we are using MadCap AMS for our technical documentation. We make food-processing machinery. There are 3 types of machines (plus a minor type, a sharpener for disc knives). In the future, there will be new machines, and variants. Each machine requires a long user handbook for the customer, and a longer service handbook for our service personnel. Due to the nature of the machinery, numerous warnings must be provided.

At the current moment, I am working on an information plan to determine the condition for the individual parts of the handbooks (e.g. warnings as block snippets, topic templates etc.). Here, I am trying to replicate DITA and structured authoring via standardized content and writing rules (e.g. a documentation bible).

However, my main issue at the moment is more on the macro-level of things, namely the folder structure and inheritance. Coming from a database approach, I need to wrap my mind around the file system thingy and project linking. I would like to maximize reuse and standardization of content, while at the same time maintaining a manageable structure.

Questions:

• Is a parent project per machinery type, with child project per machine advisable?
  
  Is it advisable to have reusable, standardized content in a folder, available for all (parent) projects?
  
  Or should this be per parent project?
  
  Does anyone have a good tip?

E.g. 1 or 2?

Archibald 1 web.jpg

OR

Archibald 2 web.jpg

[ChoccieMuffin]

There are other alternatives you could consider, such as having just one mega project with absolutely everything in it! Or rather than having 9 or 10 projects, you could have your "Globals" project which contains all the shared resources and then just one project per machinery type, and you'd control what goes in your outputs by defining targets, using conditions and so on.

So I would put all your standard warnings into your Globals project. This project would also contain other standard things like your stylesheets, page layouts, company logos, copyright text, front and back cover pages, topic to contain the index, legal notices and other standard pieces of text that would go in several outputs etc, skins (if producing online outputs), and a company glossary if you use it, global condition tag set, global variable set. Each main project would import from the Globals project, either absolutely everything, or a subset from the Globals project that you can control with conditions.

Each of your three main projects would also contain a local condition tag set and a local variable set. The local condition tag set and variable set would have the same name in each of the main projects, so that if you want to use variables in your global project (for example "Warning: To avoid losing your fingers, ensure you turn off the power to the <MadCap:variable name="Local.Prod_Name" /> before clearing any blockages!") you can do so, because the variable in the Local variable set in each big project would be defined at the project level.

Depending on what outputs you're producing, you define what is included in the target for each output. For printed or PDF outputs, the main thing that controls what goes in your output is the table of contents, but also conditions. Don't forget that you can nest ToCs, so if you have a "Front_Matter.fltoc" in your Globals project, you can nest that in the TOC for the main projects' User Guide ToCs.

[Shredder]

There are other alternatives you could consider, such as having just one mega project with absolutely everything in it! Or rather than having 9 or 10 projects, you could have your "Globals" project which contains all the shared resources and then just one project per machinery type, and you'd control what goes in your outputs by defining targets, using conditions and so on.

So I would put all your standard warnings into your Globals project. This project would also contain other standard things like your stylesheets, page layouts, company logos, copyright text, front and back cover pages, topic to contain the index, legal notices and other standard pieces of text that would go in several outputs etc, skins (if producing online outputs), and a company glossary if you use it, global condition tag set, global variable set. Each main project would import from the Globals project, either absolutely everything, or a subset from the Globals project that you can control with conditions.

Each of your three main projects would also contain a local condition tag set and a local variable set. The local condition tag set and variable set would have the same name in each of the main projects, so that if you want to use variables in your global project (for example "Warning: To avoid losing your fingers, ensure you turn off the power to the <MadCap:variable name="Local.Prod_Name" /> before clearing any blockages!") you can do so, because the variable in the Local variable set in each big project would be defined at the project level.

Depending on what outputs you're producing, you define what is included in the target for each output. For printed or PDF outputs, the main thing that controls what goes in your output is the table of contents, but also conditions. Don't forget that you can nest ToCs, so if you have a "Front_Matter.fltoc" in your Globals project, you can nest that in the TOC for the main projects' User Guide ToCs.

Thanks! There are a few considerations here.

If I have global project and one project per machinery type, wouldn't things become difficult to manage down the road? For instance if we wind up with 4 generations of machines, each with several variants. Could that not potentially result in an impenetrable forest of condition tags for any other folks? I would like to keep things KISS. After all, one doesn't want to overwhelm anyone (I am a bit overwhelmed by MadCap AMS myself at the moment).

Currently we will output two different manuals to PDF/ print. One is the user handbook for the customer, the other is the service manual our staff is sent forth with to repair and service the machines. I would maintain these as separate projects. Potentially, we would like to output the service manual digitally, i.e. to a tablet or smartphone, with all the procedure, concept and reference topics, and possibly videos. In a few years we hope to be able to provide instructions, ordering, invoicing etc. in one go based on a parts serial number.