Documents with different "Filters" / Levels of information

Question

I often have one document that needs different levels of depth for different "viewers". Typically we end up with different documents that need to be kept in sync, or color/format-marking relevance to different users.

I wonder if there's another way to deal with that, if I am the only one stumbling over that, and how you deal with it.

Example: A Specification needs:

• the "end user effect" (i.e. for discussion with the non-devs brigade)
• technological requirements (i.e. instructions for the programmer)
• rationales (i.e. notes by the designer)

Example: A Test protocol needs:

• purpose of the test and respective spec reference
• general setup and execution of the test (e.g. "create a node of type X, run command Y")
• how to run the test based on test data("open TestData-1.dat, run command Y")
• post conditions to check ("an image representing node X is saved.")
• developer notes ("this tests the case where gif input is automagically converted to png)

A "test administrator" usually needs to see all except usually the developer notes. The test runner needs to see the "run based on test data" and "what to check" instructions.

I am not looking for "access restrictions" to make the test runner never see the developer notes. I am thinking about filtering information, so that the data visible is just what the respective user needs.

As said, these are either different documents in sync, or heavily format/color-coded lengthy documents that are a pain to use.

Ideally, I'd imagine something like "Word with hideable sections".

What do you think?

Answer 1

This calls for XML and XSLT. You can easily produce various HTML views from the single original document. Editing shouldn't be too difficult either, but you need some server side scripting to do that.

Answer 2

If your document format/workflow allows it, I would recommend using the same source document and filter out the content depending on target audience. This is possible with custom XML/XSLT setups and is also natively supported by DocBook. If your documents are XML or some form of (plain) text (i.e. not binary format), you may also consider writing a custom processing script to remove irrelevant sections.

If direct tool support is not an option (i.e. when using Word), I would recommend either of two approaches:

1) Keep everything in the same document, but be careful to split the information into sections. That way the testers can ignore any sections marked as "for developers", etc.

2) Keep the information in separate documents, but be careful not to have any overlapping information in any of them (i.e. make one design document, one test document, one architecture document, etc.). Whenever you need to reference information from two or more documents, put this information in a third document and reference it there. The key here is to avoid duplicating anything between all the different versions.

Answer 3

The japanese I work with do this a lot with excel. One or several columns (leftmost or wherever) are dedicated to some flag (in your case, "info level" and/or audience). Excel has a feature to show only rows which meet a certain criteria.

It's a pain to write/maintain paragraphs in Excel, but it really works well for itemized test cases.

Answer 4

You're quite correct, this is very common. For example, in my studies of Javadocs I've seen many such situations, especially when the same function contains details aimed at clients and at people writing overriding versions.

If you are talking about code, there are mechanisms to split documentation like that; I've been working on something like that for Java/Eclipse as part of my eMoose tool.

If you are talking about actual documents, this can be accomplished if you use a logical document preparation system. For example, I often do that with LaTeX, where I have the same document, but compile different PDFs to different audiences (e.g., with or without my notes).