What are the essential characteristics of a great software solutions platform? A previous post in this blog talked about variation and evolution as two of six elements.
In dealing with software platforms, variation is how the major themes of the platform emerge. Related but different, evolution pertains to both how we understand the platform and how complexity is managed by the platform. From the outside, both variation and evolution are revealed through the Application Programming Interfaces (APIs) supported by the platform.
Just Code Something, Will Ya?
In understanding a software platform, sometimes it is useful to just make something work. A forum post on this site made a plea for a way to count the words in the Notes associated with individual Topics. That post mentions the File- >Properties->Statistics menu command, and points out that Notes text word counts are not included. There's no obvious way to get a word count for Topic Notes text. So how can we solve this problem?
Well first, exactly what is the problem?
Seems the immediate user need is a way to get a word count for the Notes text attached to individual Topics. We can generate several different problem statements:
1) A user should be able to select a Topic, choose a command off a menu, and see a Topic Notes word count in a display of some sort. That's it. The count is not stored, the user repeats the action to get an updated count.
2) OK, 1) would work, but wouldn't it be handy to have this information available all the time? We could have a Map Statistics or Map Info menu command, or maybe a floating map part, which would give a count of all the Topics, Relationships, and Callouts, together with the word count of the Notes attached to each Topic and Callout. The display could automatically update as the user makes changes in Notes text and the Topic tree, or be manually refreshed on demand.
3) Well, we already have a Statistics page in a tab dialog under a File->Properties menu command. Why don't we just add Notes text word counts to the File->Properties- >Statistics tab?
4) Cogitate on this a little more, and we can ask "Why do we have to be in an active MindManager session at all in order to get a word count for Topic Notes text? Why not be able to choose an arbitrary MindManager Map stored in the file system and get the Map Statistics, including word counts?"
Now all this may seem a little contrived, but I hope you have noticed something about each of these problem statements, both individually and as a group. What the problem statements are trying to do is specify behavior, that is, state requirements. This turns out to be harder than it looks.
The Problem With Problem Statements
First, each supposes a human user in the picture, a human with a need for Topic Notes word counts. We're discarding any notion that some other piece of software needs this information. Since the basic on-disk storage format for MindManager map documents is XML markup, other software can count Topic Notes by parsing the file itself.
Second, note how each problem statement grows in complexity by adding more specific conditions (like "available all the time" or "choose an arbitrary MindManager Map stored in the file system") and constraints (like "add Topic Notes word counts to the File->Properties->Statistics tab"). What's interesting about this is how these conditions and constraints are phrased in terms of existing behaviors seen by the user. If these behaviors are not exposed by the platform, or lie outside the scope of the platform, the problem statements become less useful. And more humorous, if your inclination runs that way. The point to absorb is that how a problem statement is structured can play a large role in how a solution is built. The basic building blocks used in formal or informal problem statements are often concepts we are familiar with, which may not be the most appropriate concepts to use in describing the problem. What you already know may blind you to what is possible. Or appropriate.
Third, we invented a term - Map Statistics - and gave a partial definition that skirted some essentials. Does the term Map Statistics include means, medians, averages and standard deviations of sentences and paragraphs within and across Topic Notes text? Do we include the parent-child Topic structure in some way? Do we actually need some sort of content analysis that mines the Topic Notes text for keywords, and grades them on frequency and Topic depth?
Finally, note how the term "word" played an essential role in each problem statement. Each statement just assumed a common understanding of what a "word" is, and went on to talk about how many there are, that is, a word count. But the meaning of "word count" is dependent on the meaning of "word." Seems like we missed something essential.
What Would a Solution Look Like?
In practice, a useful rule of thumb is to do the simplest thing that could possibly work. If we apply this to our crop of problem statements, we immediately opt for problem statement 1. Statement 2 assumes some implementation details that add complexity, while statement 3 assumes access to a user interface dialog the MindManager platform does not directly expose. While it is technically possible to use Win32 operating system services, hook the Properties dialog and modify the presentation, even from the MindManager macro language, that seems like way too much work. Meanwhile, statement 4 takes us out of the MindManager platform space all together, and into the Windows Explorer space. That's a tangent way out of scope for this post.
Further, rather than deal with the semantic meaning of the term "word" we'll take the simple route and opt for a structural definition. A word is a character sequence delimited by space characters. Period. So there will be corner cases in which our count is incorrect, like two non-space character sequences separated only by a end-of-line sequence.
So while the MindManger platform offers several ways to solve the word count problem - we could write a Save-As XSL transform, or write an add-in to compute Map Statistics (whatever those are), or write a Smart Map Part that refreshes three ways (manually, on a timer and in response to changes) - the useful solution is also the simplest. All we need is a menu command that operates on the currently selected Topics, computing the word count of any Notes text attached to the selected topics.
This is the sort of thing a macro language is made for - one shot interactions with the user, operating on an easily obtained data structure. A MindManager macro that does just that - iterates the current user selection and shows word counts in message boxes - is posted in the Downloads area. Deciding which menu will carry the macro command is a problem left to the user. However, it seems the smiling icon in the upper left corner of the message box is outside our control without some surgery on the installed binary resource files.
Of Course, There is More to Say
A more generic design would use a Visitor design pattern to traverse the current Selection, passing each Topic into the current Operation. One class of Operation could count words, another could count words, sentences and paragraphs, while a third could look for keyword candidates or something else. The menu commands would configure a Visitor instance with the appropriate Operation instance, then turn the Visitor loose to traverse the Map document.
If we anticipated that we would have to add more behaviors without changing the basic structure of a MindManager Map document, this approach has some value. Fortunately, the MindManager platform designers have been here before us. A variation on the Visitor pattern is offered by the MindManager platform in the form of a TopicFinder object. This platform feature will traverse the Topics in the map, not just the selected ones, invoking a function you supply when it finds a Topic that matches some criteria specified when the TopicFinder is defined. This is a useful feature, since it hides all the details of maintaining the Map data structure from our code.
While the topics of variation and evolution in software platforms are both broad and deep, we'll quit while we're ahead. The word count macro says we're over 1300 words, which is more than enough for now, even if we haven't found the bottom of the either subject in the MindManager platform.