4 thoughts on “Parts and Provenance”

  1. Your collection is not just a collection of topics, it’s also a collection of topic-sets. You can consider those sets as a higher level provable item that your Info Architect with the writing team and the development team will consider at the start of your project:
    What kinds of information or sets of information need to be in the set of sets?
    The results of this analysis is a document that provides a type of provenance – we thought about the whole of the collection and here is what we decided. I am sure ISO XX00X has a process for that.

    You also have the set of relationships that you define in your topics. When you create soft links (some people call them “mentions”) to identify topics that you want to refer to, you are asking for a link to that topic. You can audit the unsatisfied “soft links” or “mentions” to find out what you wanted to link to.
    Your audit meeting will, among other tasks, categorize the results:
    – don’t care
    – care, but will put off writing the target topic for whatever reason
    – add metadata some place so the mention links to an existing topic (entry in the topic, id in the soft link)
    – reword so that the mention makes a link
    – write a new topic or set of topics that satisfy the need

    Again, the results of that audit are a record that forms part of the provenance of your document set.

    1. Hi Robert. Thanks for the comment.

      It certainly could be as you say, with collections made up of other collections. The word “set” is a useful one in this context, because “set” implies a defined criteria for membership, and thus the provenance of the set is that all the members of the set meet the criteria for being members of the set and that, for finite sets, all the members required are present.

      Sets don’t have to be finite, of course, and they don’t have to be planned up front. The waterfall approach of defining the entire project up front, and then judging the outcome against the original criteria, is certainly still common. But in a more agile environment, or in an environment where you are continuing to respond to developing information needs over the life-span of the project, than an upfront list of topic set members is less useful. In those cases you may be less interested in completing the set, and more interested in having new content proved separately and then automatically slotted into the right set or sets based on its provenance.

      Part of the virtue of Every Page is Page One topics in an open ended topic collection is that you can have closed provenance for the individual topics, while having open provenance for the collection of topics. This can help inoculate your content against the kind of decay of order that generally occurs when books are maintained and updated over multiple releases.

      I chose the word “collection” to be as generic as possible, but the more specific “set” is definitely apropos here. For one thing, it helps reinforce the idea that you are creating a system in which the provenance of the set can be determined by looking at the provenance of the members of the set, which cannot be said of an assembly.

  2. Proving documents in a somewhat automated process is a hard task. There’s lots of variables in the process to take care of:
    – integrated parts of the product described
    – the environment of the product
    – use cases
    – audience of the document
    – security obligations
    – etc.

    Defining a process to ensure the provenance of a series of documents reaches a point of impossibility very soon, the more documents are involved.

    Simply approving topics or collections of topics doesn’t do the trick. A valid document always has to take context into account. A human reviewer will (should) be able to put single steps, use cases, whole topics and all sorts of metadata into context and will therefore be able to approve a document as a whole. Defined and automated processes can only check the liability of smaller parts.

    Lets take a bridge as an example:
    You can do everything right, from the planning, to calculating statics, to construction, to connecting it with roads and so on. Problem is, it’s located on a plain, no river, road or valley to cross.
    The whole process might have been streamlined and everything about it is proven – but the result is a total waste of effort as it wasn’t put into the context of its surrounding.

    I don’t want to say, that a lot of the review process can’t be automated. What I want to say is, that at some point in the process, you will need a human reviewer to check, if everything makes sense and is put into the correct context.

    This once might change, when products can “speak” for themselves, but as long as this doesn’t happen, you’ll have the need to check (almost) every documents in a review process.

    1. Hi Alex. Thanks for the comment.

      This is precisely the point I am making. You can’t derive the provenance of a document from the provenance of the information blocks from which it is constructed because context matters. The whole has to be proven as a whole.

      On the other hand, you can create a set of context-independent topics without having to prove the whole as a whole. By way of analogy, you can prove a tool box, and then fill it with proven tools, without having to re-prove the whole as a whole, because each tool, and the box itself, continues to function as proved independently of each other.

      This distinction has big implications for the cost of the review process — which matters because review is always on the critical path, and thus always directly impacts product release dates. Thus, the cost of review has to be counted not only in man hours, but in opportunity cost. (This is why product management and engineering so often refuse to hold up release schedules to ensure proper review.)

      Thus, a system that allows a context-independent topics to be reused in a collection without having to be re-proven in context in a document is such a big potential win.

Leave a Reply

Your email address will not be published. Required fields are marked *