The Organizational Irritant

A Working MindManager Sample Add-in

dethomas — Fri, 23 Nov 2007 22:04:00 GMT

There are a number of reasons why writing a MindManager Add-in can be useful. Most obvious is the desire for intimate control over user interaction, and the ability to manipulate some external system using map data as a guide. Creating an Add-in begins...(read more)

The File Explorer Map Part - Now that's a useful error message

dethomas — Sun, 07 Oct 2007 04:47:00 GMT

There is no painless way to start this post, so I'll just leap in and thrash about. This blog has been dark for several months. Since I have a day job, that's not completely surprising. Somehow I fell out of the habit of posting, if I ever had...(read more)

Creating a MindManager 7 Add-in Sample

dethomas — Mon, 16 Jul 2007 03:32:00 GMT

So I started to think about how to write coherently about creating a C# MindManager 7 Add-in sample. While the MindManager Add-in model loosely follows that seen in Visual Studio and the Microsoft Office products, there are a number of areas specific...(read more)

MindManager 7 - Getting Over Ribbon Shock

dethomas — Tue, 03 Jul 2007 16:55:00 GMT

Howdy.

I'd apologize for the lengthy silence on this blog, except I don't have a good reason beyond the stress of modern life. That and the release of MindManager 7.

I was getting ready to post an Add-in sample written in C# for MindManager 6 when the first MM7 ripples started to lap at my toes. I decided to hold off posting something new since the environment was changing. While I was holding off, MM7 launched and other threads of my life snarled up.

But things settled down, I untangled the strands of family/work/health/purpose/goals and other basic life stuff, and finally got around to installing MM7. I wanted to see how much work it would be to port the various add- ins and macros I use to the MM7 platform. But I need to keep MM6 around until my employer upgrades.

So I fired up MM7, and immediately succumbed to serious ribbon shock. The UI looks way different. Since I haven't been using Office 2007, the new Fluent UI meant climbing a new learning curve. On an application I thought I knew, thank you very much. And this is just a preview for when my employer gets around to upgrading to Office 2007, sometime after the second Cheney presidency.

But after some curmudgeonly snarling, I found this nice set of MM7 setup hints. Bringing back the task pane and workbook tabs made it easier to orient myself in the application. Hooray for Google, and hooray for the Activity Owner Wiki.

So what else is there to like in MM7? The application seems faster overall, especially on startup. Shortcut keys still work. We can save Power Filters settings as "Queries" in a map, but not outside a map for easy use in many maps. Old maps load without error or conversion. Copy my macros into the "C:\Documents and Settings\dethomas\Local Settings\Application Data\Mindjet\MindManager\7\macros" directory, and they work. Update the File Explorer with my modified version, and it works. And the UI customizations made by my MM6 add-ins - menus, menu items, toolbars and toolbar buttons - are assigned to an Add-in ribbon tab with Menu Commands and Toolbar Command groups without source code change. All I had to do was reference the MindManager 7 Type Library, change a "6" to a "7" in the registry key ( HKEY_LOCAL_MACHINE\SOFTWARE\Mindjet\MindManager\7\AddIns) MM uses to find the Add-in components, and rebuild/register the Add-ins to get them running.

I do have some annoying MM7-and-Windows Installer interactions. Upon loading some maps, but not all, the Windows Installer asks for my Office 2003 CD. I haven't figured that one out, but uninstalling MM6 will probably make it stop.

The Fluent UI has a footprint in the MindManager object model, so it appears an Add-in can add a new Ribbon Tab with one or more custom Ribbon Tab Groups, then add commands to that group. Or the Add-in could retrieve an existing Ribbon Tab and add a Group to it, or even add new commands to an existing Ribbon Tab group. In pseudo code, making a new tab goes like this:

Get the Ribbon object from the Application object
Get the RibbonTabs collection from the Ribbon
Call RibbonTabs.Add() to create a new ribbonTab object, passing a caption and a URI as an identifier. Use a URI like "URI://SomeAddInName/2007/Tabs" or something.
Get the ribbonTab.Groups collection from the new ribbonTab instance
Call RibbonGroups.Add() to create a new RibbonGroup, passing a caption and a URI like "URI://SomeAddInName/2007/Tabs/SomeGroupName"
Having the new RibbonGroup, get its Controls collection, and add your commands to that collection. This appears to be the same Controls collection type as in MM6, so the DevZone MM6 UI customization material regarding Commands and Controls applies. The basic idea is to create a Command object, which carries Click, UpdateState and UpdateCommand handlers to be called by the host, then add that Command instance to a Controls collection by way of Controls.AddButton().

But I haven't figured out how to get Fluent KeyTips to work on individual commands. Using "Tab&Name" as a Tab caption makes ALT+N the KeyTip for a ribbonTab instance, but using the '&' character in a command caption doesn't seem to make the following character a KeyTip for the command. And KeyTips don't appear in the VisualStudio Object Browser when you point it at the MM7 metadata.

All this is nice, but if an Add-in was adding commands to the MM6 menus using the mmDynamicMenu enumeration, things have changed. There are a bunch more enumeration values and the MM6 values are deprecated. You can get a grip on this by looking at the Tools- >Macro- >OrganizeMacros dialog, (Alt+F8) clicking Modify on a macro, and looking at the Menu list box. The familiar menus from MM6 are there, but they carry a "No longer used" note. Passing one of these deprecated values when creating a menu control results in an entry in the MenuCommands group on the Add-in tab I mentioned above.

There's a number of other things to explore in the MM7 object model. What does the ICustomMdiWindow interface do? How about IBrowserDialog? Or IDocumentBar?

Recalling the amount of whining I did about the MM6 object model docs, and how little good it did, I'm assuming there won't be an DevZone MM7 Object Model update for a while. But maybe I'll be pleasantly surprised.

Right now, the plan is to get my sample Add-in stable on MM7, post the source and go from there.

So I'll be spelunking both the new Ribbon UI and the MM7 object model at the same time. Bummer, but I could be flying Jet Blue.

The File Explorer Map Part - Extensions and Enhancements

dethomas — Sun, 15 Apr 2007 18:31:00 GMT

In an imperfect world, even perfection is flawed. Which you would think might make me feel a little better after rereading my last File Explorer Map Part post, but that turned out to be only true in part. What did make me feel better was compiling a list of further extensions and enhancements to the File Explorer Map Part.

Here's a fast bullet point summary of things that could be done to the File Explorer Map Part, with an eye to making it more flexible:

Let the user adjust the Skip List - There's a hard coded set of file name specifications (*.exe, *.dll and the like) to ignore when generating file system topic content in the Refresh.mmbas. script. Would be nice to keep this as a default and let the user add or remove additional specifications.
Let the user choose to always use the maximum possible folder depth - a persistent option to always expand the map part sub tree might be useful, but this expansion can be slow in the current implementation, particularly for deep file/folder hierarchies.
Display File Explorer Map Part version number - Would be handy to know what version of the map part we're dealing with in a given Map document.
Auto-expand the map part to some level less than or equal to maximum - Having a defined folder depth to limit tree expansion upon refresh might be useful.
Solicit the user to provide a prefix string for either or both File and Folder topics - There's an unused feature in the stock implementation which could be used to prefix file and folder names in the topic text. Tying this to some file specification list might be handy, say "*.txt" files get a "Text File - " prefix.
Speed up the file/folder traversal - The stock File Explorer map part uses the Scripting.FileSystemObject in a quasi-recursive manner. For more than 2 to 4 folder levels, or say more than 20 files or so, this implementation takes a while. A COM object built for the purpose could be much faster, and could perhaps support non-local-file-system protocols like WebDAV, FTP or even HTMLHelp.
Provide an optional total file/folder count as Callout or Topic Text in the File Explorer Map Part - Since we have the information, it would be a user courtesy to annotate File Explorer Map Part topic text with a count of the number of files and folders beneath it in a Map document.
Host a property grid in an actual property page dialog - If we're going to have all these user- settable values, we should put them in a Property Grid presentation, provide both default and per- instance settings, and support a "Restore Defaults" button to reset a given instance to the defaults.
Remove the smiley robot face from message boxes and dialogs - OK, now I'm just whining. But I'd like to get rid of the smiling robot icon appearing in the upper left corner of WinWrap Basic message boxes and dialogs. It clashes with the rest of the MindManager UI look. "Mawkish Macro Manifestation" is a descriptive phrase for the appearance. (Don't wince, just look it up.)

Of course, these extensions would have to maintain compatibility with prior versions of File Explorer Map Parts. Or we should create a distinct map part using the MindManager GSMP technology and avoid the issue.

While generating this list might fall into a category labeled "Here Motion Gives the Illusion of Progress," it also let me fool around with the MindManager macro language with some sense of purpose. My primary source was the Language Help accessible from the MindManger Macro Editor (Tools->Macro->Macro Editor, then in the resulting window, Help->Language Help) Sparse help topics are provided for both the Integrated Development Environment (IDE) and the macro language itself.

Under the covers, the MindManager macro language is a Visual Basic compatible scripting engine known at the time of first release (1993? 1994?) as SAX Basic. This is the name appearing in the Help topics provided by the Macro Editor, with copyright cited for "1993-2001."

By the by, if you look at the set of executable modules loaded by the MindManager application program (say using the most excellent Process Explorer from SysInternals, there's a module called "SBE6_32.DLL." The version properties of this module give "WinWrap Basic" as a description, and "Polar Engineering and Consulting" as the vendor. A second, related component, SB6ENT.OCX, also appears in the MindManager process image. These modules carry copyright info with a 1993- 1999 date range.

A reasonable guess is that MindJet integrated the SAX Basic product in late 1999-2000, and has stuck with that version since. Sort of a bummer, since things have changed in the last seven years or so.

This Visual Basic compatible scripting engine product is now known as WinWrap Basic. New .Net features are planned for later this year, it appears the Polar Engineering developers are intent on maintaining compatibility as Microsoft platforms evolve. We can hope that MindJet will pick these up at some point, without major disruption to existing macros.

If I was looking for a procedural scripting engine to manipulate a COM-based application data model, WinWrap Basic would be a very attractive option when compared to integrating the legacy Visual Basic for Applications technology from Microsoft. Polar Engineering's WinWrap is particularly attractive if it continues to evolve to support .Net technology, freeing the application data model from the legacy Microsoft COM environment dominated by IDispatch.

However, MindJet has committed to support of both Windows and Apple editions of MindManager. It may be that the COM IDispatch level may be the most appropriate point of commonality between the two editions of the product. Common in terms of the concepts exposed, not the implementation.

The only product I'm familiar with that maintains scriptable object models for both Microsoft and Apple editions is Adobe Illustrator. While Illustrator is a very cool drawing package for commercial artists, I have no clue how much effort Adobe expends on maintaining parity between the Microsoft and Apple scripting interfaces. With respect to Illustrator, it appears that Adobe obtained a certain level of common functionality, and let it go at that, choosing instead to focus on workgroup and workflow features involving the rest of the Adobe Creative Studio product portfolio.

Lacking the stable of related products enjoyed by Adobe, and operating in a distinct market segment without the deep history of graphic art production, MindJet probably doesn't have the option of "being just good enough" with respect to a procedural scripting engine. However, large opportunities exist by blending procedural scripting with declarative XML technology. Seems to me that an XProc implementation hosted in MindManager could be a powerful way to manipulate the content of one or more Map documents, hosted locally or behind some yet-to-be-designed web service.

But then again, I'm a MindJet customer. Without any knowledge of current product plans, I can wish for whatever I can dream up. Ah, such luxury.

The File Explorer Map Part - Just Deep Enough

dethomas — Sun, 15 Apr 2007 04:10:00 GMT

The other day, a co-worker sent me a mail like this:

Hey Beavis:
How come that All Files and Folders map part you showed me only goes two folders deeper than the starting folder?"

The story behind this mail is recounted in a previous post in this blog. The story behind why this coworker calls me "Beavis" is one I can't recall at the moment, if I ever knew.

In the "The File Explorer Map Part - How Deep is Deep?" blog post, I made a general (and somewhat lame) request for a modified File Explorer Map Part that would allow the user to set the recursion depth, and hence the depth of the file/folder topic sub-tree rooted in the map part.

Well, like a scab or blister or some other blemish, I couldn't leave the problem alone.

In my installation of MindManager Pro 6 (6.2.399, service pack 2) the macro script that animates the File Explorer Map Part variants is located at <ProgramFiles>\Mindjet\MindManager 6\Generic Smart Map Part\File Explorer\ENU\scripts\Refresh.mmbas
where <ProgramFiles> is the usual "C:\Program Files" folder. The File Explorer map parts are actually variations on one Generic Smart Map Part (GSMP) implementation.

By way of background, the Generic Smart Map Part is a MindManager add-in that will use the Windows Registry and MindManager Map Part information to locate macro scripts, making calls into those scripts at specific points in the lifecycle of a Map Part instance. Each set of scripts is associated with a specific Map Part.

The lifecycle points involving GSMP macro scripts are fairly straightforward. One point is the first insertion of the map part, another is upon refresh of the map part, and still another is associated with Topic context menu commands associated with instances of the map part in the map document. By default, the File Explorer Map Part adds a "Convert to Regular" context menu command that turns the map part and its children into normal Map document Topics.

It turns out that the MindManager macro language can support user dialogs with a basic set of dialog controls: static text, checkboxes, edit boxes, drop-down lists, combo boxes,and the like. There's even a handy User Dialog editor in the macro development editor under the Edit->User Dialog menu command. The macro language help topics "Begin Dialog Definition" and "DialogFunc Prototype" provide some bare bones information on using this MindManager macro language feature.

I was mildly disappointed after reading the distribution copy of Refresh.mmbas animating the File Explorer map part. The Description.mmbas script used a localizable string from the Language.mmbas module, but a number of English Language string constants still appeared in Refresh.mmbas. In addition, the recursion depth of the folders was controlled by literal constants. Further, there are several unmet error cases (try a hyperlink pointing at www.mindjet.com, for example) and some tortured logic trying to decide if the hyperlink held by the parent topic of the File Explorer map part is referencing a file, a folder or something else.

I reined in my editorial shrew and resisted the impulse to completely rewrite Refresh.mmbas. Rather, I modified it in the following ways:

added a custom attribute to carry folder depth
added a Topic map part context menu item to get folder depth from user (set every time the refresh routine runs)
set the Description and Convert to Regular Topic map part context menu items to reference the right scripts
added a MsgBox call in the QuitOnException exit point
added "No Hyperlink" and "Hyperlink does not point into file system" tests and error messages
used the language.mmbas module to carry all the constants used in error messages, user prompts and topic attribute identification
added logic and error messages to detect some missing or invalid parent Topic Hyperlink cases

All this involved writing a new script called FolderDepth.mmbas to carry the user dialog to set the folder depth. This script includes a test to validate the user-supplied folder depth against maximum and minimum values. Since there is apparently no convenient way to force the user entry to consist of digits only, this test has to accommodate arbitrary non-numeric characters.

So now I can set a folder depth to control the recursion that builds the child topics beneath a File Explorer Map part. If you want this code, see the Modified File Explorer Map Part download, and follow the installation directions. However, use it at your own risk. I'd like to hear your reactions, good or bad, but I can't promise to fix every possible problem. See the readme.txt file in the download for a description of installation, use and returning to the original File Explorer Map Part functionality.

The File Explorer Map Part - How Deep is Deep?

dethomas — Mon, 09 Apr 2007 03:29:00 GMT

I had another one of those "how does this work?" moments with MindManager the other day. A colleague was using MindManager to document a software installation process, mapping binary image locations in the target file system with the install steps that placed the image there. When I innocently asked "Did you use the File Explorer Smart Map Part to get the file list?" I got one of those "Huh?" looks.

You know, the "Huh?" look. The one where you ask someone a seemingly simple question and they look at you like there's a funnel growing out of your forehead, or you're speaking in tongues, or professing a desire to maintain legacy code or something.

Turns out my colleague had never used the File Explorer map part that ships with MindManger Pro. If you open a Map Document, then open the Map Parts task pane, you can select the "File Explorer" category folder to reveal three Map Parts: "All Files and Folders", "All Files" and "All Folders". Drag one of these onto a Map, and place it beneath a Topic that has a HyperLink pointing at a file system folder, and the File Explorer Map Part grabs a snapshot of the folder contents and formats it into Map SubTopics. Which beats the heck out of switching between Windows Explorer and MindManger, copying and pasting file and folder names. Or at least my co-worker thought so, since that's what he'd been doing for 50 files or so.

The MindManager Pro help explains all this better than I did. See the "Using Smart Map Parts" page in the help for details.

But the next day I received an e-mail that ran like this:

Hey Beavis:
How come that All Files and Folders map part you showed me only goes two folders deeper than the starting folder?"

It was my turn to say "Huh?" Sure enough, if you point the HyperLink of a Topic at "FolderX" and add the "All Files and Folders" Map Part to that Topic, you get the files in FolderX, and the child folders in FolderX, and the children (both files and folders) of those child folders, and that's it. But we needed at least three levels below the starting folder. I had assumed the File Explorer map parts would just recurse to the end of the file/folder tree, but that isn't the case.

Well, Smart Map Parts (SMPs) are a nifty part of the MindManager Platform. Briefly, they let you put script behind a Topic and run that script to obtain Topic content. So there had to be some script code around somewhere that ran when the File Explorer Map Part was inserted, and some more script that ran when that Map Part was refreshed. Some digging around in the Registry (thanks be for the Edit->Find command in Regedit.exe) produced a key with a ScriptPath value like this:

HKEY_LOCAL_MACHINE\SOFTWARE\Mindjet\MindManager\6\AddIns\Mindjet.Mm5GenericSmartMapPart.AddIn.2\SMPs\Mindjet.FileExplorer.Smp.1

Turns out that in the English version of a MindManager Pro 6 installation, there's a folder called
<ProgramFiles>\Mindjet\MindManager 6\Generic Smart Map Part\File Explorer\ENU\scripts
(where <ProgramFiles> is usually "C:\Program Files") and in that folder is a MMBasic script called Refresh.mmbas. This is the code that animates the File Explorer Smart Map Part. Seems likely that other languages are in a similiar folder, replacing "ENU" with a language-dependent identifier. Buried in the Refresh.mmbas code is a snippet like so:

    Set attr = folderTopic.Attributes("http://schemas.mindjet.com/MindManager/GSMP/2003")
    t = attr.GetAttributeValue("Type")

    If t = "Files" Then
       showFiles = True
       maxDepth = 1
    ElseIf t = "Folders" Then
       showFolders = True
       maxDepth = 2
    ElseIf t = "FilesAndFolders" Then
       showFiles = True
       showFolders = True
       maxDepth = 2
    End If

' Everything is OK, ready to go
Call recurMap(folderTopic, mapPath, 0) ' map files and folders
folderTopic.SetLevelOfDetail(1)

Hmmm.... Looks like this is where we decide what sort of update we're going to do, and set some control variables to achieve that result. Look around some more, and it turns out showFolders, showFiles and maxDepth are all global variables, used in a subroutine called recurMap to control the scan of files and folders starting at a folder provided by the user in the HyperLink carried in the parent Topic.

Usually, I break out in hives when I see "magic numbers" in code, that is, numerics used in the manner of "1" and "2" in the snippet above. In this case, I wimped out and just mailed the code snippet and its location to my co-worker with a "don't set maxDepth too big (like 10 or something) because the map will take a year to refresh" caveat. But I also made a copy of the Refresh.mmbas file and added code to use constants like these:

Const MAX_FILE_DEPTH = 1
Const MAX_FOLDER_DEPTH = 6
Const MAX_FILEFOLDER_DEPTH = 3

Which is how I learned about the long file/folder scan time. But this got me to thinking. Shouldn't the user be able to select this level (and possibly the default) for individual File Explorer Smart Map Parts? And shouldn't there be a way to put an SMP command on the Topic context menu to solicit the user for this settting? The DevZone content talks about a "Generic SMP" framework that hosts user SMP scripts, and mentions pre-defined context menu items for use by such a map part, and the MMBasic language help has a Dialog keyword. Seems like it should be possible to combine these to get a "how many levels deep" value from the user.

I'm hoping someone has already done something like this. And I'm hoping that someone will post a modified FileExplorer SMP on the Downloads/Map Parts page. I may feel guilty (or bored, or inspired, or something just plain bloody-minded) at some future date and cobble up a modified File Explorer that lets the user set the folder depth of the Topic content created by an instance of this Smart Map Part, but then again it might take me until the second Reno presidency to get around to it.

MindManager in Software Development - Creating Tables From Topics - Part 3

dethomas — Sun, 18 Mar 2007 23:38:00 GMT

"Once more into the breach, dear friends," spoke Henry the Fifth, delivering the line Shakespeare wrote in 1600 or so. We're not invading France in the early 1400's as Henry was, but the line seems to fit. This post delivers the third version of a software development sample, and like Henry I'm growing somewhat weary but am too proud to give up.

But no one is hacking at me with a sword, nor am I stuck on a plane in Philadelphia, so life could definitely be worse.

The point of doing this sample was to demonstrate the use of MindManager in software development. The problem at hand is the creation of tables from Map document Topic content. A MindManager macro implementation, MakeTable, is available for download.

This version incorporates additional content in the areas of architecture, design, test and implementation, and expands the background material topics. The sample itself is attached to this post. A Software Architecture Description map template included in the attached content is also available as a separate download.

From Skepticism to Enthusiasm by Way of Text Markers

dethomas — Sat, 17 Mar 2007 18:06:00 GMT

Originally, I didn't run out and get a copy of MindManager to become a Customer Evangelist. I don't like to admit it, but somehow I've become one, at least locally and with a very small 'e'.

That's evangelist, sotto voce, not a gadfly Evangelist, or the embarrassing EVANGELIST, which is followed by fanfare, distant cheering, divine imperative commands, luminous messages written on the inside of your forehead, insidious menacing opposition, ale with dwarves and elves, hordes of orks crossing the plains at a lope, talking trees, enslaved masses, battles with darkness, etcetera and so on.

It's just that people keep asking me questions about how to do something in MindManager, even if I'd rather talk about guitars. Or beer. Or software architecture. Or rocket surgery and brain science, or surgery science and rocket brains, or even rocket science and brain surgery, though I don’t normally dissect my personal problems in casual conversation.

Despite these qualms, this week I found myself in two different conversations with two different co-workers on the general tangent of "I have this MindManager software, how do I use it to ..." One person is trying to organize a piece of a large business process integration project, while the other is trying to capture, summarize and publish department activity status reports over time.

The interesting thing is that one MindManager feature turned out to be useful in two different contexts - Topic Text Markers. And I didn't have to write code to obtain a good outcome.

A Problem of Integration

The Integration Project person has a mass of details to deal with. This is raw material for a potentially large map or set of maps, organized around structural elements of the project - stakeholders, customer data-sets, legacy systems, upgrade procedures, enterprise system rollouts, etc. But there were a number of themes running through these structural topics and areas. For example, how to connect the stakeholders using legacy system X, maintaining data-set Y, with the two different-but-related enterprise applications meant to replace X, but that will become available for adoption at different times? This person wanted to pick a main topic and have the map re-orient around that topic, sort of like the Personal Brain presentation discussed on the map navigation thread in the MindJet User Forum. The number of these kinds of connections made map Relationships among topics unwieldy.

But when I demonstrated the Text Marker search feature on a trial map, shazam, a dubious user became enthusiastic. We invented a Text Marker (I think we used the word "Slugs") for a phase of the integration project, tagged everything that cared about that phase, and then searched across the 50 or so Topics for that Text Marker. Generated by a Topic Text Marker search, the navigable list of Topics tagged as "Slugs" was what turned the tide. The idea that sets of Text Markers are completely user defined and a given Topic can have several Text markers from the same or different sets was icing on the cake. This user suddenly had a sense of control over a morass of details that had seemed overwhelming.

So if you haven't yet, check out Text Markers and the Search task pane. Beat it up a little, Text Markers are under the Options link in the Search task pane. If you have several Map documents linked to a master Map, the Search for Text Markers works across them in Multi-map view. Trick, very trick.

Meetings, Bloody Meetings

The Status Summary problem belonged to a different person with different goals. This person attends department management status meetings, but was unhappy with the flat Word documents used to capture the meeting results. To paraphrase, the problem goes something like this: "This meeting minutes Word format thing is fine the day of the meeting, but I want a larger picture, one that shows progress on action items over time. I don't want to dig through a pile of documents to find out who did or didn't act on action items for improving how we do process X or whatever it is we're working on. I want to generate some content to post on the SharePoint site without doing a lot of cut-paste-point-click stuff, and I want it organized by subject, not date."

Since there's usually a number of activities going on in parallel, some sort of status meeting to ride herd over the work seems needed, at least to the management folk involved. Each meeting report has the same three major sections: Attendees (who's at the meeting), Discussion Items (what they talked about), and Action Items (what they did or are going to do about some subject area). Part of the reason for the meeting is to provide senior management with a sense of what is happening on a given subject. Who took what Action Items and did they get it done yet?

Since there are direct and indirect lines of reporting in this case, a phone conference is more comforting to management than reading e-mail or discussion thread posts and generating a mental picture of progress on a given subject. And meetings are, after all, the practical alternative to work.

Well, the meetings happen weekly. Seems to make sense to have one Map document to hold the meeting minutes info, a Map Part to provide the three main common Topics for each week, and to add subtopics to each of the three meeting Topics to capture individual bullet points. But how to produce a summary rolling-up the details for a given set of related action items? This user is starting to wonder if this MindManager thing is really all that useful after all.

If you thought Text Markers on Topics, maybe you're psychic. That's what jumped out at me. By tagging individual Action Item topics with a Text Marker giving the controlling subject of the action item, a once skeptical user was able to generate a complete, chronological action item list, on a given subject, using the Power Filter to hide all Topics not marked with a given Text Marker. With the desired content visible and the rest hidden, it is only a few mouse clicks to generate Web, Word or HTML Help documents giving the actions and results. Automating this by creating temporary summary topics for each Text Marker in the Action Items group is only a macro away. And I won’t have to write it. Maybe.

Brown Paper Packages Tied Up with String....

So Text Markers on Topics, coupled with the Search task pane and the Power Filter, is my favorite MindManager thing this week.

Two different user problems solved by the same product content filtering features, leaving the user in control of how filtering is performed and the identity of the filtering terms, that's a good thing.

Two people feeling more effective in dealing with their seemingly endless problem data, that's a good thing.

One reluctant customer evangelist wondering "How did I get here? Where's the men's room?" well, I guess I'll have to live with it. To paraphrase Will Rogers, stupidity might have gotten me into this mess, but it won't get me out.

MindManager in Software Development - Creating Tables From Topics - Part 2

dethomas — Mon, 12 Mar 2007 04:48:00 GMT

So we're back with the second installment of the Table Creation sample, rolling up Part 1 into Part 2 of a description of the MakeTable macros. Attached to this post is Part 2 of the Table Creation sample in both Word and .CHM formats. I'm using the rolling update model, so Part 2 includes the Part 1 content, lightly augmented and copyedited.

Part 2 introduces the Architecture, Design and Test sections. While I have draft content for additional sections dealing with Implementation and Delivery, those sections don't appear in the attached content.

But I spent too much time on Table Creation sample content, and not enough on the BackGround Material. The Background Material sections dealing with Architecture, Design and Test software development activities fell behind the content. Those sections need some work in terms of content and references. While the structure of software development Architecture, Design and Test content need not be as formal as use cases, a map template or two would be useful in maintaining consistency.

I'm having trouble breaking out time to work on this during the week, and sessions in front of the keyboard during the weekend aren't getting other things done. Could be that it's time for some serious marriage maintenance. Or I can just sleep under my desk and not explain this behavior to my wife. But that doesn't sound like a viable long term strategy.

Regardless, I decided to post this to get a stake in the ground.

On a related note, has anyone besides me experienced some unrecoverable errors after using the HTML Help Builder from inside or outside MindManger? I modified version 1.0.7 to let topics hidden in the source map remain hidden in the Complied HTML Help output, but it is hard to see how those changes would cause MindManager editing problems. I have experienced MindManager crashes with and without the Library task pane open when deleting icons from topics, and when closing a map after generating a .CHM without that map loaded. But the Map recovery feature didn't kick in at next MindManager startup, even with the lock file present. Seems strange. I don't know if the MindManager development group has signed up with Microsoft to obtain crash dumps, but there is probably some useful information buried in there. If I had worlds enough and time, or maybe a debug build, I'd be tempted to dig around in that material.

MindManager in Software Development - Creating Tables From Topics - Part 1

dethomas — Mon, 05 Mar 2007 04:05:00 GMT

One of the things I've done with MindManager is write software requirements as Use Case behavior descriptions. Since I wanted to generate another post about creating Map document Notes tables from Topics, it makes some sense to write a Use Case describing what this MindManager MakeTable macro should do.

This is an example of step one in a three part software development formula - first understand what it is the software should do, then make a solution work, and then make it work better.

As I got started, I realized the Use Case would make more sense in context. So I adopted table generation as a sample software development problem. The first installment, demonstrating the use of MindManager in creating use cases, is in the attached zip file, together with background information about requirements capture with Use Cases. The same content is found in two formats - compiled HTML Help and as a Word document. The .compiled HTML Help file contains a Use Case Map Template, this template is also posted in the Downloads section of this site.

Here's an excerpt from the attached sample:

This material is an example of the use of MindManager in software development. The subject at hand is the creation of tables within MindManager Topic Notes in the context of an interactive user session.

As a sample problem, table generation is complex enough to warrant a solution, small enough to easily understand, yet big enough that work in the areas of Requirements, Architecture, Design, Test, Implementation and Delivery need not be overly contrived. The first part of the story covers table creation requirements through a Use Case and some Policy and Practice statements. Subsequent parts will deal with other development activities.

There is something appealing about using the MindManager product to develop and document an extension behavior for the product. If nothing else, we have a clearly defined application domain for the effort.

An unstated assumption runs throughout this material, we'll mention it here and then leave it be. There is a big difference between performing software development and managing software development. This material is not meant to endorse a single development method or process. If a waterfall process, or a spiral process, or an iterative method, or another variation on the agile development theme floats your boat, go for it. My view is that good ideas (and good people) breed other good ideas (and grow more good people) as long as management doesn't go out of its way to shoot itself in the foot. The material presented here, using the sample problem as a basis of discussion, are things I regard as good ideas in software development. However, like any other tool or technique it is possible to use these things incorrectly. "By their works shall ye know them" says the Bible, and this applies to techniques, people, teams, technologies and organizations as well.

In the end, software development is about how people can use their time, talent and the available technology to produce something useful, possibly valuable and perhaps even beautiful. If the ride is also exhilarating, fun and satisfying, then you are fortunate as well as gifted. But I also believe that neckties are commonly used in corporate culture to hide the marks left by sphincters, so what do I know?

Assuming I can maintain the momentum, I plan on expanding this sample with additional content. Where I see the opportunity, I'll point out how MindManager supports software development activity.

In fact, I'll do that now. The compiled HTML Help file in the attached zip file was created with a modified version of the most excellent HTML Help Builder. I brazenly steal the map template in that download, including it in the sample content attached to this post. I made several modifications to the 1.0.7 version of the HTML Help Builder - one to style the Topic Hyperlinks in box with a pale yellow background, a second to omit hidden Map Topics from the generated HTML output, and a third to remove the '*' character from subheadings in the help pages. I plan to forward these changes to MichaelS for possible inclusion in some future HTML Help Builder revision at his discretion.

Without MindManager, I wouldn't have bothered to create the HTML Help form of the MakeTable sample. By using a MindManager Map to create, organize and refine the content, it is straightforward to publish in several formats - Word, web and HTML Help - repurposing the content for different uses.

Turning Topics Into Tables

dethomas — Mon, 26 Feb 2007 05:28:00 GMT

One formatting thing I seem to do a lot in MindManager is fool with tables in Topic Notes. I often treat a Topic like a file card, and wind up stuffing a lot of information into the Notes attached to a Topic. But maybe this formatting task is a consequence of the kind of content I'm creating in MindManager.

Much of my time in MindManger is spent capturing requirements and architecture content for software systems. One of the things I like about MindManager in this usage is the ability to move, subdivide and link to topics. A second thing I like a lot is the ability to generate Word documents or web content from a MindManager Map document.

In the beginning, I would be beavering away creating and organizing Topics in the map, and often leaving the Notes text window open to quickly capture additional material on a given Topic. But Notes content that was fine in the map at time of capture often left a lot to be desired when I came back to it later, and really fell short of a satisfying result when I started to share the map content as Word documents and web pages. So I would spend time cleaning up the Notes text, and as a consequence, spend time and effort trying to create tables in the Notes content. And wind up with stray rows or several unconnected table sections when I created Word or Web content from the map.

If table editing is sort of awkward to use, why bother? Well, in general tables can be a useful way to group together related information like definitions or glossary entries for the reader.

I also use tables to capture logic conditions and outcomes in a sort of decision table format. This is useful for stating all the conditions a given piece of logic should cover in a MindManager Map document by collapsing sub-topics for each condition into a parent topic for the piece of logic.

Sure, I can open up Word, format a table as I please, then use the keyboard wizard to copy that table from Word and paste it into the MindManager Notes editor window. While this works well for tables with three, four or more columns, it's sort of a pain for simpler tables. And if I need to modify the table content, I'm back in the Topic Notes editor window, fooling with the row insert button or something.

So what I needed was a macro or helper or something that would format tables for me, using content in the map. And that's what I wrote. The current version is posted in the Downloads area, the SeeMeMakeTable.jpg file attached to this post gives a rough idea of what the generated table content looks like.

Along the way, I discovered that MindManager Topic Notes cannot carry nested tables. Here's a crude nested table example.

If you try to paste a table into an existing table, you wind up with three distinct tables in the Topic Notes. One is the table content ahead of the insertion point, the second is the inserted content, and the third is whatever original table content comes after the insertion point. I didn't experiment too much with splitting and merging cells, but it didn't seem to matter. Pasting one table into another resulted in three tables and some funny formatting.

Topic Notes are stored as XHTML markup, the MMx object provides access to this content. If you force the issue by formatting the XHTML markup for a nested table and assigning it to the Notes content, MindManager crashes. Oops. Don't do that. So the macros in MakeTable.zip look for table markup in child Topics, and just turn it into text. They also expect a Boundary around the parent and child Topics, complain if there are no child Topics found, or if no parent Topic can be found, or if there are too many child Topics, or if either the Boundary, the parent Topic or some child Topic is not selected when the macro run.

I'm thinking this "create table" problem might be a good one to use in talking about MindManager use in software development. Not too big, not too small, not too contrived. But we'll see what time allows.

MindManager as a Platform - Revisited

dethomas — Sat, 27 Jan 2007 20:32:00 GMT

It's been a few weeks since my last post. Somehow time just passes when you're not looking. There's a John Lennon quote for this - “Life is what happens to you while you're busy making other plans.” Or working on other problems.

I'm somewhat disappointed in the dearth of comments on the Six Elements of Greatness posts. Of course, maybe no one cares, or the posts are too long, or too dense or not immediately useful. Or all those things. Or those posts (and the rest of this blog) just make me sound like a pompous jerk.

But these six things - Unity, Theme, Variation, Evolution, Balance, and Hierarchy - provide reason and rationale for why, where, when and how a platform feature should be exposed. In good platforms (and good products, good art, good engineering and so on) these characteristics make their presence felt, supporting each other in meeting goals and enhancing the experience

When these six characteristics are at odds with each other, we get bad platforms (and bad products, bad art, bad engineering and so on). The experience is awkward. If we can't escape (and buy/use/own something else) we may find ourselves in the role of apologist, rationalizing bad work and awkward results through selective perception and revisionist history.

Whew. Glad I got all that off my chest.

Moving On...

In an attempt to generate a little blog momentum, I thought I'd close out the platform post series by listing the good, bad and awkward points of MindManager 6 as a software platform. Most of this I ran across while composing the Six Elements posts, or in writing macros and add- ins. Each list and its content is debatable, each is fodder for future posts. Or comments, questions or cream pies. Or something.

The Good Points:

MindMaps are a great free-form, tree-oriented way to capture and organize information for a wide variety of uses
User interface can be customized by user without writing code. Check out this nice UI toolbar addition at RobinZ CAD Blog
Automation object model exposes map document content and most of application user interface
Add-in model allows external components (and developers, yeah!) to provide new extensions to user interface and command logic
Macro editor has a form of keyword completion, type-sensitive method/property help, syntax check command, a step through debugger and a reasonably small footprint
Library, Map Parts and Map Marker task panes provide convenient access to supplementary map elements
Smart Map Parts are a nice way to package up and reuse functionality
New Icons, Text Markers, Images, and Templates can be organized and shared via the Library
Topic Attributes can store new data properties on a per Topic basis
Business Topics are associations between Topic Attribute sets and logic
XML data formats allow out-of-band use of map to create and present content in other forms, act as user-side of legacy applications or web services.
Import button on Explorer, and Word is useful in capturing content for map topics
Auto-recovery of maps is seamless
Application Update via Help menu is handy way to obtain MindJet-supplied service pack

The Bad Points:

MindManager will not launch as an OLE Automation server. There is a mysterious, intermittent General Protection Fault after use as Automation server, which seems to require a repair install to recover normal operation. (This may be pilot error, MM launches in Javascript/VBScript just fine...)
Only one MindManager process at a time.
An Add-in cannot create a submenu on the existing Topic right-mouse context menu (While an Add-in can add new commands to the Topic context menu, it cannot create a brand new sub-menu. Nor can it insert new commands in the Insert, Icon Marker, Text Marker or Image sub-menus that are parented by the Topic Context menu)
No support for a multi-map collection in object model, no collection of maps linked to by this map
Notes content supports a subset of XHTML transitional, cannot embed information in comments, no use of <hr> <div> or <style> tags, no link or meta tags, no raw HTML edit/copy/paste, no superscript, no subscript, no image map support, no nested tables, etc.
Notes content makes extensive use of inline styles, making modern styling harder to do.
No direct support for new Vista features - file tagging, sidebar, visual themes, etc...
No information on command line startup modes - Benchmark, Bookmark, Mode, etc. which hints that these will go unsupported in the future. A "diagnostic" mode would be useful in giving the development team some clues on problematic behavior. Try the command "MindManager /?" for a summary of these modes.
The developer documentation could be more helpful. More samples, more links among content, some indication of the type returned from a method or property accessor like Document.Selection, all these would be useful. Further, better formatting of the DevZone content would make it easier to follow what samples are provided. The code examples use &#160 (&nbsp) extensively as content to tables whose width is 100%, so I see one long, wide block that runs off the right edge of the brower window. Not very useful...

The Awkward Points

This list fell apart into several lists : Product Stuff, Object Model Stuff, Markup Stuff and Macro Stuff. These points aren't generally deal- killers, but rather just sort of irritating in the right (or wrong) context.

Product Stuff

Spell checker doesn't ignore words in all caps. Or handle first letter capitalization of new dictionary entries.
Multi-map web export is difficult to find, slow to run, awkward to modify, no common table of contents, CSS, index, etc. among resulting pages. And hyperlinks in Topic Notes that point at external map topics do not resolve to HTML pages, even if those maps are in the Multi-map Export, but rather point to a complete map file stashed in a child LinkedDocument folder. Click the link in the browser and you're prompted with the Save/Open/Cancel dialog. Not too useful.
Word Export seems to ignore target template and styles in favor of creating MMxxx paragraph styles. So getting Map document content into a particular Word format is a pain.
No in place editing of maps using OLE technology, so no embedding maps in Word, Excel or Visio
No support for hosting OLE embedded/linked objects, so no adding ActiveX controls to a map, even in a Task Pane.
Topic Call-out positioning is not intuitive. Call-outs don't stay where you put them relative to Topic
There's a "Right Map" topic layout on the SubTopics Layout tab of the Format Topic dialog (try the Format->Topic menu command) but no "Left Map" option. This makes some forms of maps dealing with "several inputs, one result" sort of a pain to deal with.
No image map editing in Topic Notes. Would be way nice to have a way to create hotspots to other topics or external URLs in Notes images.
A way to browse a Map, say a Map Explorer tree presentation, would make some edit, find and re-write tasks easier
Power Filters help control topic visibility, but cannot be saved for later use

Object Model Stuff

Object model documentation lacks examples, cross-references, related links and even complete entries in some cases.
Cannot set the wait cursor during operation and have it stick, the cursor is reset to an arrow
Cannot intercept the "delete topic" event to prevent user deletion of a given topic
No inheritance of Business Topics, Topic Attributes among topics, smart map parts, etc
No abstraction to support sets of linked maps, say a "parent" map linking to several "child" maps
No abstraction to support storing, loading and applying view filters set by user
No means to "compare maps and find differences" in object model.

Markup Stuff

Wrong XHTML namespace for hyperlink targets in Topic Notes markup. Sometimes the namespace is given as "'http://www.w3.org/1999/xhtml'" instead of "http://www.w3.org/1999/xhtml". Note the extra single quotes. (But this appears to be fixed in 6.2.399.)
Dirty flag in XML map markup just adds to file size bloat
XSD content could carry more information in <xsl:documentation> tags. If http://schemas.mindjet.com/MindManager/Application/2003 is going to resolve to a document, let's make it an informative description of the schema. Seems like the license info is longer than the <xsl:documentation> content
XSD schema files are available both in local file and via resolvable URL (this may not be a bad thing....)
<span> and <font> tag usage, together with inline styling in Topic Notes content works against more flexible content styling techniques. Think Cascading Style Sheets, someone.
No nested tables in Notes content.

Macro Stuff

Cannot disable or replace the smile icon in the upper left of macro message box displays
Cannot handle events in the macro language

That's a lot of bullet items, but it is the sort of content and feedback useful to product design teams. We can only hope that the MindManager development team considers some of these things as time passes and new MindJet products emerge. And keep on using MindManager to generate, capture and organize information in interesting ways.

Platform Greatness - Balance and Hierarchy

dethomas — Sat, 06 Jan 2007 18:42:00 GMT

Two of six elements of greatness remain in this series of software platform blog posts. These are the topics of Balance and Hierarchy.

Balance? Like On One Foot?

With respect to a software platform, balance speaks less to the notion of equality and more to the relationships among different behaviors of the platform. Not every aspect of a platform, as exposed by the Application Programming Interface (API), will receive equal weight. But in a useful platform, there is a working equilibrium, a sort of harmony, among the various parts of the API.

Distinct from this view of platform balance is the notion of hierarchy as a way to manage detail. The basic idea of a platform - a chunk of technology that can be extended or specialized for a particular purpose - is itself a form of detail management. There are a number of aspects to an executing computer application. Examples include lifecycle, user presentation, application logic and data storage. When we build upon a well- constructed platform, we may simply take these aspects for granted. The platform handles them.

Taking a broader view, a computer operating system itself is a platform example. It is not necessary to understand heads, sectors or rotation speeds in order to write a file to a hard disk. (Be grateful. Be very, very grateful.) The operating system exposes an API involving handles and read/write buffers. Using this interface, an application can treat a disk file as a contiguous logical entity even if the actual file contents are scattered across disjoint sections of the physical disk.

Just as an application reading a file doesn't worry about the physical disk location of the data, a MindManager macro or add-in extension doesn't care very much about the actual memory layout of a Mind Map. The MindManager platform deals with loading the map into memory, displaying menus, drawing topics and so on. The macro/add-in can just concern itself with operating on a specific part of the map when the user asks it to do so. This separation of concerns is a good thing. When separations of this type are easy to make and maintain, the platform is demonstrating good behavior, enabling extensions with appropriate effort.

Exposure Need Not Be Indecent

We've used the verb expose in the sense of becoming visible or becoming known. MindManager 6 platform functionality is exposed in two main ways - an object model and an XML document schema. The MindManager object model provides access to both map content and the application when MindManager is executing. In contrast, the map XML schema describes a map markup format accessible on disk, with or without the presence of MindManager the application.

As MindManager creates, saves and loads map content, data moves between the object model and the markup format. The object model provides access to a set of currently loaded maps in the context of an executing MindManager process, while the markup format for stored maps permits out-of-application processing on map contents. Further, we can obtain XML markup from a MindManager object instance, or create a new instance by supplying markup.

Object Model Conventions

When dealing with an object model, there are several distinctions to keep in mind. One is that the term object has been grossly overloaded in the literature. The root meaning and latent power of object-oriented programming concepts has long since been obscured by strata of marketing and other twaddle. Lucky for us there a just a few fundamentals to understand. The rest reveals itself with use. The better you know the application as a user, the better you can employ the object model to solve problems.

The first thing to get straight is the difference between the class of an object and an instance of an object. A class acts as a definition or specification for data and the code which acts upon the data. These definitions are used at runtime to create object instances which carry and manipulate data. The platform developers define the classes, we as platform consumers write code to create and manipulate instances of those classes.

Another object model distinction is made between application classes and document classes. For the MindManager platform, application-related classes deal with an executing MindManager process, allowing us to iterate all the open documents, open dialogs, embellish the user interface with menus or menu items and so on. The main class used here is named Application; one (and only one) instance of this class is created when MindManager loads and is destroyed when MindManager exits.

If an object can be created, saved and later loaded as part of a map, it is an instance of a document-related class. In the MindManger object model, the chief object of this kind is called the Document. We can pretty much equate map Document instances and files. The object model provides methods to allow the examination of the current collection of Documents, the Topics carried by a given Document, and the variety of objects that can be associated with a Topic - Notes, Icons, Relationships, Callouts and so on.

Sets or groups of object instances are handled in object models through the notion of collections. Using one abstraction, the collection, for different kinds of objects means the same techniques used in iterating Icons will also work for iterating child Topics. The extension developer can learn one thing, the collection, and use that knowledge in many places.

MindManager XML From 50,000 Feet

There's a boatload of material available on XML and related markup technologies, we won't dive into that technology here. However, while the W3C XML page carries links to the actual specifications, reference books are also useful. One comprehensive reference is the Essential XML Quick Reference by Skonnard and Gudgin. This covers several markup technologies, including Extensible Stylesheet Language transformations (XSLT). This transformation technology is a powerful tool for converting XML content to other forms, say generating HTML web pages from a MindManager map, or converting a structured table in Word or Excel into a MindManager document.

MindManager maps are inherently tree structures, formed by parent-child arrangements of Topics and related objects. This characteristic fits well with the basic "nested tags" structure of XML documents. Having a reasonably well-designed schema, the MindManager markup is extensible. We can add new kinds of data to the map, data the base MindManager application knows nothing about, and still edit the map while maintaining the new data. It is worth noting that XML schema defines markup structure, much as a class defines an object. Likewise, a given piece of XML markup is like an object instance, it is defined by some schema and carries data in the form of attributes and text content. There's a direct correspondece between tags in the XML format and object instances in the MindManager object model. And this is a good thing.

Markup and its use in the MindManager platform to too broad and deep for this post to continue with the topic. However, by exposing and consuming map content through XML technology, the MindManager platform makes some forms of further extension straightforward. One way to get started with this side of the platform is to create a simple map in MindManager, save it as a .xml or .xmmap file, and open that file in a browser such as Internet Explorer. Both the structure and the content of the map are captured in the markup format used to create these files.

Balance and Hierarchy in Practice

There are many examples of balance and hierarchy within the MindManager platform, but this post is getting overly long. A forum post asking for a way to display both ends of a Relationship gives us an opportunity to show an example of platform variation and hierarchy in practice.

The Document Object abstraction in the ExpandSelectedRelationships macro gives an indication of the leverage provided by balance and hierarchy. The Document Object class acts as a parent to the Topic class, the Boundary class and the Relationship class. The macro walks the current object Selection, and gets a Relationships collection, if any, from the current object. The macro then walks the Relationships collection, which can carry only Relationship instances, each Relationship joins two DocumentObject-derived instances. The macro calls the SnapIntoView() method of each DocumentObject instance.

The balance part of this example is how the MindManager platform lets the user choose the objects and presents them to macro code in the Selection object as part of the object model. We're interacting with the user without doing much work. We could operate on a saved map file, reading map markup and looking for hidden Topics, Relationships and Boundaries, but that seems ham-handed.

The hierarchy part of this example is how we can rely on the SnapIntoView() method of a DocumentObject instance to take care of showing the object to the user. We don't have to worry about the details of positioning the drawing page, finding a hidden child topic or boundary, deciding if some map content is hidden or not, and all the other details of drawing a map. The macro just calls SnapIntoView() on both Relationship endpoints and moves on to the next Relationship in the collection.

What's Not To Like?

While this post has pointed to several aspects of the MindManager platform as examples of good balance and hierarchy, there are some gaps in the platform as well. Here's a brief, incomplete list of places in the platform where the extension developer does too much work:

No way to store a filtered view of a map for later use in this or other maps. If you want to apply the same filter to a set of maps,you're pretty much on your own in defining the view and storing/loading/modifying that definition
The Power Filter is not exposed in the object model, so if you want to hide map content marked by specific content, say all Topics with the stop sign icon, you are reduced to iterating the map and making manual tests.
The platform provides no diagnostics or performance monitoring to help the Macro or Add-in developer decide if his design is too big, too slow or just awkward. If the platform was instrumented, so the time duration of an operation was easy to obtain, it would be easier to decide what needs to be optimized.
While the BusinessTopics abstraction is a useful way to add custom properties to a topic, and supports editing those properties in a purpose built user interface, BusinessTopics are defined entirely by function calls in code. A data- driven model would be more useful to the extension developer. A similar comment holds for adding new menus and menu items
The object model has the notions of an ExternalTopic and an ExternalTopicHandler, intended to allow Topics to be created "on demand", say from a database or some external source. This works, but a more useful, less awkward API might use the notion of a "TopicProvider." This idea supposes a component that can be plugged-in to the MindManager platform, and be available as a source of Topics, Callouts and other map content.
There's no provision for creating sub-menus on context menus, particularly the Topic content menu. So extensions have no way of mimicking the "Send To" or "Icon Marker" sub-menus seen when a Topic is right-clicked and the Topic context menu is displayed.
The platform lacks ways for dealing with sets of related maps. While the use has a Multi-Map view, there's no collection of those maps available in the object model.

But these complaints are somewhat removed from the basic behaviors exposed by the platform. Each deals with a somewhat more advanced use of the MindManager platform in extending or specializing the MindManager product. They aren't really defects or problems, but rather opportunities to make a good platform better.

Platform Greatness - Variation and Evolution

dethomas — Sat, 30 Dec 2006 21:37:00 GMT

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.