Unsurprisingly, when trying to abstractly model behaviors, events and processes in a given domain or system, dissecting and studying actual, concrete scenarios plays a critical, dual role: experimentation with real-life material, that exhibits the exact behvior we are trying to model, not only proves a very helpful way to ground and strengthen the understanding we have of the phenomena we are describing (thus enabling us to model them), it is also a necessary step in validating such a model: real-life examples provide the required test-beds allowing us, iteratively, to refine, adjust, and ultimately design a model suitable for use beyond the examples actually studied. This methodology (draw an abstract model from concrete experiments, then validate the model with more real data-points) is very common (see Eliyahu Goldratt’s take on it in his Theory of Constraints).

This approach can obviously be applied to the domain I am covering here: building and maintaining structured knowledge. What are good models for such knowledge building systems? And what is a good, real-life scenario where such a system would be useful, so I can dissect and study it, build a suitable system, and eventually use it to generalize a model of such systems.

One such scenario is the challenge to produce useful functional specifications for software products I am working on. Usefulness is a concept we could philosophize about for a while, however in this context it simply means that the document (in its evolving revisions) is a reliable and exhaustive source for reviewers (who came up, directly or not, with requirements from customers) to determine whether what we’re planning on building is up to their expectations, while it also is a precise enough source of information for developers to unequivocally build the said piece of software. This simple definition carries a lot of constraints, as it pushes onto the specification the responsibility of ensuring that the product eventually meets the requirements, but that’s what a specification is about, after all.

First, such specifications clearly constitute a valid scenario of structured knowledge: they are meant to convey to readers a massive amount of structured information about a product that is being built, they need iterative refining and evolving, and due to the nature of the contributors and consumers of these documents, they need co-authoriing and workflow processing support (to run through cycles of iterations). By nature, their content,and the implicit decisions it reflects, need to be justified to both the readers charged with validating the underlying requirements, and the readers tasked with implementing a suitable software component matching the same: thus, functional specifications (and their maintenance) exhibit the characteristics of a typical structured knowledge system.

Second, functional specifications are, in my view, an interesting problem to tackle, because while no-one will typically argue that anything larger than a small development project should do away with them, instantiations of such documents that truly meet the usefulness criteria above are very rare. Building useful specifications, therefore, can’t be simple, and frequires solving a number of complexities that we’re bound to face with any structured knowledge base, so that solving these functional specifications issues will help solving the more generic issues of structured knowledge. On the need for evolving, useful functional specifications, read Joel Spolsky’s articles, Painless functional specifications.

I position the features of a support tool for such a task (building useful functional specifications) along two dimensions:

• Process Management This dimension groups all the features related to the process of co-authoring structured documents: workflow, notifications, inline editing and commenting, change management, fine-grained addressability and so on. These features are pretty much orthogonal to the type of structured documents the group is trying to author.
• Structure and Content Management This dimension is more specific to the domain or type of knowledge being accumulated. In the case of functional specifications, the structure of the document, once ready for review, must make it easy for readers to understand what product they are going to get if developers build according to the specification. This structure is very fine-grained, and I would say it needs to be adjusted to every type of software product being built. For instance, if we’re building packages where the user interface plays a big role (as opposed to, say, a faceless package that solves a particular type of math equations, or implements a given networking protocol), then the structure must place a lot of emphasis on the graphical interface, leave none of it to the reader’s or the developer’s imagination, otherwise the contract that the specification represents isn’t precise and fine-grained enough. For enterprise application software, for instance, 2 key elements of the specifications should be screen-shots of mock-ups and possibly performance indicators of response time to the end-user. Determining the right structure and format (possibly using templates) for the completed document is, thus, a fine-tuned exercise that will affect vastly the usefulness of the effort. The importance of structure and format relates back to the learning quality of a knowledge base: how well it allows readers to grasp the concepts it carries. I don’t believe there is a unique format, best suited to convey any message. Instead, just like professors will pick and adjust educational tools and methods to best explain concepts they are communicating their students, the nature of the knowledge to share should drive the format of the communication. Rich on pseudo-code snippets when algorithms are discussed, rich on video, screen-shots when graphical interface is key, etc.

The one feature set that relates to both the tool and process used to build and share knowledge, and that knowledge itself, is the group of features exposed to allow editing of the document in the most convenient fashion. Whereas auditing, approving, tracking comments are all tasks pretty much orthogonal to the content they are processing, the tool(s) used to edit this content are inextricably dependent upon the structure of what is being edited. Text is the common denominator, but if you want the tool to be aware of the structure (in my example, if you want the tool to know about features, sub-features, dependencies, assigned resources, priorities, etc.) and facilite authoring along the natural structure of the product being specified, then you cannot be generic, instead you have to use a rich, specific editing tool. Fine-grained addressability actually falls in this category, since allowing reviewers or co-authors to edit video clips, or images, assumes they have the ability to make precise references to portions of such elements.

Now, what does this mean for my current challenge, building useful specifications? I will start by enhancing the XML Schema describing specifications tailored to my current project. While this enables me to embed images, even audio and video clips, addressability remains an issue. Then I will need to tackle the problem of how to render the document: I am thinking of a very dynamic, multiple views XSLT style-sheet that gives multiple perspectives to different readers, or enable one reader to successively focus on different aspects of the software being described – one important aspect is to keep conveying the context, regardless of the view, to allow readers to know where they are in the document. This set of issues are very specific to the domain of software functional specifications, and even constrained to the type of software I am specifying – I will tackle these first, in order to make sure I can at least come up with the right underlying and presentation models. Tools for process management, as described above, are more generic and I will tackle them when the structure and content management features are clearly defined.