One document – multiple architects

[Markus Bauer]

Hi,

I am evaluating eaDocX v3.9.3.17 for the automatic document generation from our EA model.
Currently, for the (single) architecture document, multiple architects are working on different components/features, so they are working independently on different packages within the EA model and update the corresponding chapters in the architecture document manually whenever they are ready to release their current work.

The goal is now to switch to eaDocX (restructuring the EA model, creating a template for the architecture document and replacing the component/feature specific chapters with eaDocX sections generated from EA content). As the architects are working independently, also the release dates of the feature specific chapters will vary. So whenever an architect wants to update the parts of the document he is responsible for, he doesn’t necessarily know anything about the status of the other features. So he should only update his chapters.
What is the best approach to do so? Is it even possible to update only parts of the document in a releasable shape?

I tested the “Generate this section (draft only)” option in eaDocX, but that of course doesn’t create a releasable document, as neither of the tables of content/figures/tables is updated. And it seems that the table numbering in the updated section gets messed up, if there are other tables in previous chapters (at least for me it showed the caption “table §” for all tables instead of numbers in my test)

If there is no “one-click” solution for this, can somebody give me a hint how to setup the model/configure eaDocX (e.g. by using some script magic or by using stereotypes to distinguish the releasable parts from the non-releasable parts somehow) to be able to update only parts of the document? Or is it only possible by splitting the document into several feature specific documents?

Thanks and regards
Markus

[eadocX Support]

Hi Markus,
This is a really interesting question – I’d totally forgotten about the Word Master Documents idea, but it looks to be the right solution for your requirements.
So I went back and looked-up how Word Master documents work, and they just seem to ‘include’ other documents. Getting the heading levels to match-up is a problem, but I think I made it work.
What I did:

1. created a Word master document, (outside eaDocX), and added some hand-written content
2. added two Word sub-documents
3. opened each of the sub-documents in eaDocX, and added some EA content in eaDocX sections
4. generated each of the sub-documents
5. went back into the master documents, and I could see the non-EA and EA content in all the documents.

OK, so not a surprise – an eaDocX document is just a Word document, with your settings saved inside it.

Question is – will this change how you get to use eaDocX?
Here are some of the things which will happen if you follow this approach.
Key idea is that, when generating each sub-document, eaDocX will treat it as a stand-alone document. This is just based on knowledge of eaDocX – I haven’t tested each one:

1. you will only get cross-reference hyperlinks within a sub-document. There won’t be any hyperlinks between sub-documents. This will affect the readability and coherence of your document
2. Features like ‘cross reference reports’ will only work within a sub-document, so if anyone uses them, you may get duplication
3. You’ll need to make sure the heading numbering levels are consistent across the sub-docs, but that’s the case anyway, and at least eaDocX lets you control the top-level heading number
4. Figure and table numbering may not work. We create proper figure- and table-number tags in Word, so I’m hopeful that when Word merges the documents together, Word will resolve these correctly
5. Glossary will be per sub-doc, unless you make the master document into an eaDocX document, and give it a single section which is a glossary. Then it MIGHT detect all the contents in sub-documents, and create the correct glossary list. I’m not confident about this one

These are all the issues which come to mind – I have a feeling there will be more.
But overall, if you bear in mind these restrictions, then you should be able to make a Word master document from eaDocX sub-documents.
‘hope this help – if you do get this working, can ask you to please update this entry, so others can benefit form your experience. We might even include this idea in the help for the next version.
Ian

[Markus Bauer]

Hi Ian,

thanks for your quick and detailed response!

Yesterday I talked to some colleagues who have some experiences with the Master Document approach of Word. All of them told me: FORGET IT!

According to them, it is very slow and crashes from time to time. In one of the projects (non-architectural document with around 10 sub documents), it even stopped working completely in the end. Since then, trying to generate the complete document always fails at the point of expanding the subdocuments. So they needed to create the document from scratch by manually copying & pasting the content of the sub documents to a new document. Fortunately, after sending it to the customer, no further maintenance was needed. That is of course different for architectural documents, which may need maintenance for years or even decades.

I cannot judge whether the problems are inherent to Word or whether we may have used it in an improper way, but for now I think I will follow a slightly different approach. I will (let eaDocX) generate independent Word documents for the features and (manually) add references to these documents in the main architecture document. This way the architects can work on their components independently and release new document versions whenever they want without affecting anybody else. Does it make sense?

I have created 2 additional questions with respect to this approach in

1428-placeholder-in-document-template and 1429-custom-information-in-document-information

It would be great if you could have a look at them.

Thanks and regards
Markus

[Author]

Posts