Suggestions on how to edit and manage related documents

Help / Discuss
1

Today I started an evaluation at editing a couple of software engineering documents inside our XWiki instance (runnint 14.10.x) and wondered whether the workflow makes sense, there are alternatives available that I’m not aware of and so forth.

Please consider that in a few passage I’ll refer to a copy-macro, I didn’t find anything like this, it may be not the best way to handle the situation, etc. so I’m open to suggestions.

So, basically the documents are:

  1. the Requirements Document, that would hold a somewhat structured list of customer requirements about a project
  2. the Analysis Document, that would dissect each requirement and examine it in depth, review it, merge two together, etc.

I thougt the following:

  • the Requirements Document is a normal wiki page, where requirements are separated in sections (paragraphs with headings)
  • the Analysis Document is a separate page in which I make use of a copy-macro that behaves like this:
    • it will allow to extract text from the Requirements Document, targeting a specific section (much like the Include Macro already does)
    • but the targeted section text is copied (fixed) in the Analysis Document when this page is saved, and not updated when the page is viewed
    • when the original section in the Requirements Document is edited, the copied text in the Analysis Document will stay the same as when it was copied, but a banner or similar would advice (in view mode) that the section has been updated in the original document

Does this all make sense to you? Do you handle similarly related documents in diffferent ways? Are there extensions that better fit my scenario?

A couple of extra info:

  • I discarded the option to merge the two documents in a single one, adding the analysis inside the Requirements document, because I’d much more like keeping the latter a separate, leaner document (plus it may have a separate audience from the other)
  • I’ve considered using annotations but they feel a bit too unstructured, instead a wiki page allows to leverage all the editing, layouting and macro capabilities available
2

I would use XClass and XObjects and sheets.

3

Thanks.

About sheets you’re referring to this: https://extensions.xwiki.org/xwiki/bin/view/Extension/Sheet%20Module ?

4

Yes.