Thoughts On Support And Maintenance

One of the eternal challenges about designing a bespoke system seems to be making sure that it is supportable in the future by getting all the information about it available to Those Who Need To Know. Furthermore the range of information is very broad, ranging from descriptions of the business purpose of functionality to descriptions of individual objects and their attributes. Consequently is is often very difficult to hit upon the most appropriate for of documentation.

For example, if I have a data warehouse fact table for which there is a single foreign key column that is nullable then some documentation is called for. When you describe that table through SQL*Plus that nullability really leaps out at you — how do you document the reason for this design decision? Maybe through a comment on the column, stored in the Oracle data dictionary, but how many people ever look at that kind of thing? Some people aren’t even aware that such a feature exists. How about a document in a shared folder? Maybe, but people are always tempted to print it out and put it on a shelf somewhere, and it’s always tricky to arrange formatting and organisation of such a thing.

Another example: “This table has multiple materialized views defined as ON COMMIT REFRESH COMPLETE so a commit will appear to take a longer time than usual”.

It seems to me that what is needed is a general repository of information for an application that is easy to update and easy to view, to allow comments to be stored againt tables, indexes, column, triggers, packages and whatnot. The feature of being easy to update is to me critical. If it is going to take someone more than a couple of minutes to write a note then realistically they are not going to make much effort to do so.

So anyway, it seems to me that a Wiki would be just the thing for this — easy to search, easy to modify, easy to link from one article to another. Thus I can have an entry for my fact table, say “FCT_SALES” that either links on to columns or has a subheading that allows me to annotate the information that column “SALES_ACCT_CD” is obsolete and all values are null from 2003-01-01 onwards, for example.

It also seems that it would be handy to be able to add in more generic subjects, such as on table compression and the problems in trying to update compressed data, with links to online Oracle documentation as well where appropriate. In other words, notifying support persons about the major issues associated with the use of particular features and providing links for further reading.

Wiki’s are not exactly at the cutting edge of technology anymore, and their very purpose is to collect and catalogue a wide range of unstructured data. They seem like just the thing.
Another thought: I do not understand why companies are so enamoured of support solutions that lock away problems in a database somewhere with a client-server style front end. Is it beyond the wit of man to use in the technical support field what we so often use in the real world — a forum approach? Again, it’s easy to update, easy to search, and open to all. Maybe back the whole thing up with more formal bug tracking and problem logging software for the usual password change requests and formallly identified issues, but there seem to be so many questions on the use of an application that a forum would be an ideal mechanism for sharing the knowledge.

Now all I need is someone willing to try out the ideas, or report on their own experiences with such methods.



8 thoughts on “Thoughts On Support And Maintenance

  1. Well, you hit the nail – what people are willing to use. What I’ve noticed over many different ways of doing this – usenet, email lists, otn, bbs, wiki, c$erve, blogs, etc. – is each has a life cycle. As long as people are willing to use them, each works fine. When people go on to something else (or it mutates or gets spammed to death), it dies. Some reanimate – particularly those that are based on an infrastructure that remains stable over time. Different formats do tend to emphasize different styles – for example, blogging seem to make it easier to have longer and more detailed posts than usenet posts, bbs even shorter – but having too many options dilutes them all, makes it easier for things to die.

    I work with an obscure 4GL, the vendor has a web-based support system with a kind-of-clunky but useable interface for searching the knowledgebase, a forum, and there are usenet, list and (I think) google group fora. Almost none of the fora are used. So that’s pretty useless. I speculate that is because most users are developers and functional analysts, and so are either too busy just plain doing work, or have an attitude of having to figure any thing out by themselves. Or maybe there’s a critical mass necessary for any of these things to work. If that is the case, having too many options could be a bad thing. Of course, there are probably many factors, but, going back to the oracle universe, note how many functional analysts and developers go to the big conferences, and contrast that to what you see on fora – there isn’t a – I think that shows where people focus. And asktom demonstrates that a hunger is there, at least for developers.

    Maintenance, on the other hand, needs to be focused on the particular site and app. Maybe a wiki could be appropriate – but again, everyone has to use it. When I do development, I tend to code as though I’m going to be hit by a bus and then come back with amnesia (which is about how I am anyways, even without the bus). When I do maintenance coding, I can see people often just assume the next person can figure everything out from the code, even if it’s entirely obfuscated; I generally do something between carrying on whatever traditions I find, and how I think it should be done. I usually add some external text description in some place I know will be backed up, and also often copy that to email too.

    A wiki still doesn’t solve the fundamental problem of documentation immediately being out of step with code, whether it is written before or after (or in) the code. It might help with the problem of being easy to maintain, and therefore more likely to be maintained. While, as you say, wiki’s aren’t at the cutting edge of technology any more, that’s not as important as whether it is an infrastructural object that can last over generations of technology. It’s relatively new from that viewpoint, and the change tracking of knowledge within wikis hasn’t really standardized, I don’t think.

    Now, I’m a pack rat, and I have some code from the early ’80s sitting in a file cabinet in my basement. It was written in the style of self-documenting, highly commented code. And you know what? That can work! I can look at it now, and see what the heck was going on. Is that useful? No, this stuff is long gone. But when it was still around, it was very useful. If one needed to document for non-technoweenies, one could always hack comments to a file. Overall visions of design, processing flow, and how things fit together would still be an issue, of course. And that hasn’t changed, even with all the CAD tried over all these years. Visio and Powerpoint might make things easier, I suppose. I don’t know, I don’t use them, I just describe things in English.

  2. Nine (yes Nine!) we did this for a customer – a whole on-line “how to fix in the dead of night” manual in our nice new Lotus Notes enviroment… but several names over the door later and Notes is about to be replaced with…. oh, never mind and now we need to plan how to replicate the functionality in the new world. Just wish I knew the best answer

  3. I think that one issue that provoked this thought was that we seem to be movingfurther and further away from the world of written code into all sort of fancy GUI’s, for better or for worse. Take Informatica, for example. A completely GUI interface that makes some allowance for comments, but always tucked away in a text box on some screen or other. At first glance this seems entirely appropriate but it is difficult to link from one comment to another, or to put in a lot of text and have it formatted in a readable manner. If you integrate it with shell scripts and Oracle views and procedures then where do the comments for those go? I’d suggest that it’s a tricky business to decide on where to put comments in such cases and people poossibly have to remember several methods of adding and reading them. It really needs to all be taken out to somewhere very accessible.

  4. Funny you should mention wikis…. I’m just starting to bail out of the entire wiki business, since no-one seems to want to use the one at Dizwell.

    Instead, I’m going to be opening a Drupal “book”: a series of collaborative pages that can be authored by anyone, linked to any other pages using standard HTML, arranged in a hierarchy of chapters, pages, child pages and so on. Pages can be added, deleted, promoted, demoted, assembled into chapters… and then the chapters can be promoted, demoted and so on.

    A couple of big benefits arise from this approach. First, ownership of the content: anonymous content has not been a great success, but Drupal Books have each of their pages attributed to a site member by name.

    Second, only the page author (and me!) can edit the content of submitted pages. Others can add comments to a page, but the page content itself is invulnerable. The thought of Anonymous Joe wiping your work through accident or malice has, I think, been a big factor in people not using the Wiki more.

    Third, a Drupal book is part of the whole Drupal-managed site, so it gets indexed and included in the Site Search results. The wiki is a separate application, completely standalone and hence invisible to the Site Search function.

    Fourth, all wiki software I’ve ever tested has been chronically slow -presumably because a lot of display interpreation takes place (replace odd wiki-specific syntax with standard HTML, for example). A Drupal Book is just a standard web page, is already in proper HTML format and needs no dynamic re-interpretation for it to display correctly.

    I suppose that brings me onto the fifth big benefit: no weird wiki syntax, just standard WYSIWYG editing or plain vanilla HTML.

    It’s early days yet, and I am still thinking my way through the concept, so the Knowledge Base is not uet open for general public submissions… but the principle underlying it is certainly one that you might want to think about: a collaborative “book” or “reference manual” sounds exactly what you might be after…

  5. Hmmm, very interesting. It sounds much more structured than a wiki, what with chapters and suchlike, but maybe it works well without that aspect as well. It sounds, though I may be wrong, more oriented towards larger articles than small information snippets.

  6. Don’t be fooled by the names. If you remember how the original wiki’s ‘Article Index’ was split into sections (‘Concepts’, ‘RMAN’ etc) -well, those are your chapters. The individual article wikis become the ‘pages’ within the chapters. The comments you can add to those pages are like pencil annotations in the margin of a real page of a book.

    It actually all works quite well, and there’s no more structure to it than there was in the original wiki (so there’s some ‘organisation’ involved. But not much).

    And I very much hope it will get used for short paragraphs of thought, though it suits closely-argued novellas of insight, too!

  7. Interesting.

    At the job-before-the-job-before-this job, a colleague and I were frustrated by the lack of any place we could store (and look for) knowledge about the products we developed. The only solution was to read the code and figure it out, or else track down the guy who wrote it and ask (if he was still with the company).

    So we created a PHPBBS in about half an hour on an old linux box that no one was using. For the next month every time we discovered something, we added it in there. We created different forums and it all grew quite organically.

    Unfortunately it soon became popular and others were using it. I say “unfortunately” because word got back to management and rather than congratulating us on this, they squashed it. Perhaps because we were charging customers less because it took us fewer hours to find solutions? But officially it was because we had no approval for this. Never got it, either. Instead the company wound up spending big money on something that I don’t think ever got rolled out (and if it did, no one ever used it).

    However, I’ve been recently told that the forum is still secretly alive – hidden somewhere.

    One final thought: I always viewed our inter-connected web of blogs as a discussion forum. Posting something is like starting a thread, and you can read the comments for other people’s thoughts. Or, people can start their own thread after they read your blog. And they’re all aggregated together through RSS feeds or one of the aggregators.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s