Chris Doig's Blog

Excel 2007 can’t open Lotus 123 spreadsheets

We hit this problem today trying to export a Notes view as a spreadsheet, and import it into Excel. Older versions of Excel could import a wk4 spreadsheet, but not so in Excel 2007. Maybe IBM / Lotus will finally provide a means to export native Excel files directly from Notes (or maybe this is just wishful thinking...!)

Color Blind Spreadsheets

While working on our Sox projects I was emailing spreadsheets around. To help track progress I "traffic lighted" certain cells: Green for no problem, yellow when I was waiting for someone, and red when I had to do something myself. I was using Excel 2007, but those receiving my spreadsheets were using Excel 2003. Every time I saved the file, Excel 2007 would wand me about a minor loss of fidelity but I paid little attention. That was until one user complained that there were no green cells on the spreadsheet – only yellow.

Now I must admit to being color deficient (or partially color blind). So when I chose green for the cells, it was a bit of a yellowish green. And when Excell saved my spreadsheet in 2003 format, it changed these green cells to bright yellow! My guess is that the 2007 version of the program uses 24 bit color (like a photo), whereas the 2003 version uses only 8 bit color (like a gif file). And when the 24 bit color was downgraded to 8 bit, the yellow green was changed to bright yellow – totally altering the meaning!

So beware when using Office 2007 and 2003 products in a mixed environment. Things can bite you if you are not careful.

Teamstudio Seminar in New York

Last week I presented "Notes Management Best Practices" at the Teamstudio seminar in New York. Decided to take the red-eye on Tuesday night, flying Jet Blue. Well, Jet Blue was great; but flying the red eye was not such a good idea! After a 4 hour flight from San Diego I arrived at the Dylan hotel, only to crash and sleep until after lunch. Then went for a short walk - toured Grand Central station (I love trains, so this was great fun) and walked down Park Avenue until the cold got a bit much. Wednesday evening I had dinner with the Teamstudio team at the Chemist Club restaurant- it was great to finally meet the folk behind the emails & phone calls. I must say that the bread in New York tastes much better than most of the bread you find on the west coast.

Dinner with the Teamstudio Team at the Dylan Hotel, New York.

Thursday morning saw us assemble at 8:00am in the Dylan conference room. First off with the Keynote address was Ed Brill from IBM with a look at where Notes is going for the next few years. As somebody who didn't make it to Lostusphere this year, the presentation was very interesting. After a short talk by Nigel Cheshire on "Building a Strategic Plan for Best Practices" it was my turn to present "Best Management Practices for Lotus Notes". Using the analogy of a ship, this presentation focused on how to steer the ship rather than how to make the engine run efficiently. Based on the audience feedback at the end of the day, it seemed that most people found the presentation useful. Jesse  Segovia from Elanza Group had the tough after lunch session, and was later followed by Rob Axelrod from Technotics. Rob is an excellent speaker, and made a very enjoyable presentation on the development process and build automation. We finished the day at about 4:00pm, just in time to catch heavy traffic back to the airport. The flight back to San Diego to over 6 hours, and culminated with an aborted landing due to fog. I finally crawled into be at 1:00am after a very long day.

For reference, my presentation is attached in Power Point format.
Click link to download file
NotesBestPractices43.ppt

IT Projects and Documentation

Hands up all you developers out there who document your in-house IT projects properly. I thought so! Almost nobody does. Good documentation makes software projects easier to use and maintain, but is seldom written well, and sometimes not written at all. Documentation is usually left to the end of the project when interest has wained, and not seen as adding much value. It is something developers would rather not do, something that is put off as long as possible, hoping the need for it  will fade away. Unfortunately all that fades is the memory of the project, making the code yet harder to maintain.

An ounce of prevention is worth a pound of cure. Let me illustrate that with a personal experience from last winter in San Diego, California, when we had the 3rd wettest winter on record. For some time I had suspected my roof might be developing problems, and early in the previous summer I had hired a roofing company to check out and fix the roof. During this process my neighbor (who has the same house design) asked the price. Being neighborly I told him, and got a look that said... "You haven't got leaks - you must be nuts!". In due course my neighbor was transferred to Japan for a 3 year tour of duty, and he let his house to tenants. Came the winter rains and water started pouring though his roof, damaging dry wall inside. Of course tenants don't get problems fixed as fast as home owners, which made it even more expensive. I'm guessing, but he probably paid at least 5 times what I spent for his repairs. Had he been proactive in fixing his roof, his costs would have been much lower.

Likewise, good documentation significantly reduces the cost of using and maintaining software down the line. Timing is everything. The sooner documentation is written, the less effort it takes (because it is fresh in peoples' minds) and the better the result. But the real trick for producing good documentation with minimum effort is to turn it into a collaboration project between developers and users.

Collaboration to the rescue

If we in the IT world are so interested in electronic collaboration, why don't we harness it to help us solve the documentation problem? The secret to improving documentation is to efficiently harness the thoughts and input of all involved in the project when they have thoughts and input. The labor of writing the documentation is not so much the actual writing of the text, as knowing what to write. Timing is everything, for example developers should document the purpose of a field when that field is created. And if end users have a problem with that documentation, they must be able to add comments, ask questions while they are working with the software. A good example of a collaborative documentation project is Wikipedia, the on-line encyclopedia. You could consider collaboratively maintained documentation a moderated wiki project.

Essentially the idea is to turn every page into a collaborative effort. To implement this, end users and developers must be able to add comments to a page while they are reading it, because that is when they see the problems. Typically users will find that...

• Documentation is ambiguous.  Other people don't make the assumptions the author made, and immediately see ambiguity problems that the author will never notice. And as more users from different cultures mix, the potential of ambiguous writing increases.
• Documentation is wrong - it is out of date, or there is a bug in the code - and it does not behave as expected.
• Documentation is incomplete, either partly or totally missing.

Every page of documentation has an owner. When users add comments to that page, the owners are notified by email. After reading the comment the owner then initiates an action, e.g. posting a potential bug to development, correcting the documentation etc. Once the problem is taken care of, the comment discussion is archived and the updated page is ready for use again. In this way documentation becomes almost "self maintaining". You can see simple examples of this on the web at the bottom of technical pages, e.g. on the Lotus Notes Knowledgebase they ask several questions and solicit you input. While this is a step in the right direction, it usually is a very weak implementation of collaboration because there is no ways for the doc owner to contact the person who made the comments.

One further collaborative though it to use IM (Instant Messaging) in the documentation. This is an intriguing idea that I have yet to try in a meaningful way. However, if you use the Lotus Notes client and Sametime together it is trivial to add.

What is software documentation?

Let's begin by defining what we mean by software project documentation: It is a collection of documents related to a software project, aimed at a target audience for specific purpose. Any software project has several kinds of documents associated with it. At a high level these are...

Document Type	Target Audience	Purpose / Description
Requirements	Software architects, end users.	Defines what the end users want, and is the"target" the development team aims for.
Software Design	Software developers	Describes how the requirements will be metwith the developed software, and how that software will be built.
The code itself	Software developers	(special case)
Test cases	Software developers	Describes how to verify that the user requirementshave been met.
User instructions and help	End users	Describes how to use the software.
Development Standards (usually not projectspecific)	Software Developers	Describes conventions adopted by the organization,and the reasons for those conventions.

Most important is what documentation is not: Documentation is not a story. Many people approach documentation as though they were writing an essay at school. This bad approach is positively encouraged by the page layout of word processors, e.g. MS Word. It is important to realize that documentation is NOT a story, but is a collection of many documents, all related to the same subject.

When should you write documentation?

One mistake that is often made is to leave the documentation to the end of the project, which invites problems. Documentation is a continuous process that starts before the official start of the project, and continues after the official end of the project. The tail end of the documentation can be considered part of the project maintenance.

The raw materials for documentation are notes, questions, ideas etc. To get the highest quality documentation content it is very important to capture that raw material while it is fresh in people's minds, so make it easy for them. Some examples are:

• Suppose Mike is a software developer working on the project, and adds a field to a form. He should immediately add that field to the help documentation and explain the high level purpose of that field, for example why that field was required. (No need to add where it is used etc., as an up to date version of that is best extracted from the code). He can do it in point form, and flesh it out later. But capturing that information early is vital, because it is fresh in his mind. Even leaving it to the next day will cause him to occasionally forget important details and subtleties.
• Suppose Jack is using the software and finds a problem. He adds a comment to the manual, which emails Mary, the owner of that page. Having a free moment, Mary reads Jack's comment, contacts Jack and has a short discussion about the problem. Since the problem is fresh in Jack's mind, the two of them can effectively resolve the problem quickly. As an added bonus, Jack feels that the software development team is really "on the ball", and they are all one team working together for the good of their company. Of course, had Mary taken a month to get back to Jack he would only remember the frustration with the software, and would have forgotten all the details. Not only is it more difficult to resolve the problem, but the "on the ball" team building effect has been lost.

At the project start take a very high level approach to documentation by developing an outline. Realize that the outline is very fluid, and will change substantially as the project proceeds and the documentation is fleshed out and refined. An initial outline will typically cover requirements, design and architecture. A useful technique is to flesh out the end user manual before the code is written. Of course as the product is developed, the user manual is updated. This forces a number of design decisions to be considered early, and results in a higher quality end product.

When writing the documentation always capture the reason why a decision was made. You are capturing the context of a decision, which makes it easier to maintain. Later on people forget the context of that decision, and then have difficulty deciding to change it. For example, I was recently trying to fix a problem with some code I had written a few years back. I had not recorded the reason why it was written using such a peculiar way. Having forgotten the context, I rewrote it in a more convectional way to fix a problem and add an enhancement. When testing the modified code I discovered why the other peculiar approach was used, and had to rewrite it the original way (due to the nature of the change, I could not simply roll back to an earlier version). Of course, the code now includes the reason why this peculiar approach was used so I won't make that mistake again!

Managing documentation

As mentioned above, the problem with using word processor for documentation is that it forces you into "story" or "book" mode, whereas project documentation is a large collection of relatively short, related documents. If you don't use MS Word for documentation, what do you use? I have found a Notes database to be a very good tool. Potentially there are other ways to do this, but because Notes works so well, I have never needed to explore any further.

Once you realize that project documentation is a collection of many related documents that are collaboratively maintained, project documentation becomes a mini document management project. This naturally leads to the document lifecycle: create, publish, collaborate and update, retire and archive, something that is well handled by standard workflow techniques in a database. Managing project documentation as a collection of documents in a Notes database makes the whole task much easier.

All documents should have an audit trail or revision history so that you can go back to old versions. This audit trail should be entirely automatic, requiring nothing from the user except possibly the reason why the document is being updated. Disk space is cheap - you can keep almost any number of old version for as long as is required. Again this is relatively easily implemented in a Notes database.

One of the biggest mistakes we make is to think that documentation is complete. It very rarely is. Since the documentation is a database, updating one page does not require re-issuing the entire package. Actually, if the documentation is really "alive", it will be being updated continuously. Since documentation is a collaborative "living" effort, it must be on-line, and can't be on paper. While it can be printed out, paper is obsolete the moment it is printed (but realize that it can be hard to get people off paper). One very useful concept I have employed is to track the "percentage done" of each page. You create a few set "percentage done levels", e.g.

• 0% - Title done (placeholder, used to build the outline)
• 25% - Started work
• 50% - About half way
• 75% - Nearly complete
• 100% - Done

You assign one of these levels to each document. To start, you create the outline by creating pages for each logical heading in the documentation. Don't worry if you create too many or too few - the pages changes as the documentation is worked on. At the document level this is a very crude indicator of the work done, but at the chapter and database levels (i.e. in a categorized Notes view) it provides a very good indication of how much work still needs to be done. It also shows where effort must be focused to complete the work.

Where do you document?

As mentioned earlier, I like to use Notes databases for project documentation, which allows me to keep most related information on the project in one database. Typically requirements, design, and user and code documentation exist in that database, and this forms the bulk of the documentation. Documentation with a specialized workflow such as bugs, enhancement requests, ownership etc. is better managed in a project management database. (See also Thoughts on Managing In-House Software Development Projects in this blog.) And of course the best place to document the code is in the code itself. If you have a tool to generate the documentation from the code even better. Best of all is to use such a tool to create the documentation on demand (because the documentation is always up to date), but that isn't always practical.

User Documentation for Notes Projects

This is a section specific to Notes, and Notes application development. Once developers decide to use Notes for on-line user documentation (i.e. help) they must decide where to put it. The worst place is to put the help in documents in the database. Reason? - at least 2 versions of the help must be maintained - one in the production database, one in the development database. And if the database design is ever cloned, the problem compounds. As we know, it is impossible to manually keep nontrivial collections of documents in sync.

This leaves two choices - either hard code your help into the database design, or put it in a separate database. Both of these allow you to maintain only one version of help. For small, relatively simple database,adding the help as design elements is a reasonable approach. Typically if I was create a template that formed part of a database design, e.g. config documents - I might put the help docs in the design. But in recent years I have all but moved away from this approach.

For anything substantial (i.e. more that 2 or 3 days work) it makes a lot of sense to put the help into a stand alone documentation database. This database should be a standard template developed for the purpose and reused across multiple projects. As the design elements are created, the programmer can add notes to the help documentation database. For example, if the developer creates a field on a form, he can jot down a few notes on why that field was created as he creates it. As the project develops, so this documentation gets fleshed out. Finally, documentation can be upgraded as required, e.g. if a users has a problem, add the answer to the documentation and send a link. Thus the documentation is continuously improved.

Conclusion

To sum up, the main points to consider are:

• Documentation is a continuous process that starts before a project formally starts, and continues well after the formal end of the project.
• Timing is critical: capture documentation content when raw content is fresh in people's minds.
• Project documentation is not a story; it is a collection of related documents that must be managed.
• Treat documentation as a collaborative effort, much like a wiki to reduce costs and improve quality.

I trust this gives you some ideas on how to effectively create and manage project documentation.

Using code headers to make LotusScript easier to maintain

This article is an example of a simple technique that, when put into practice, can make LotusScript much easier to maintain. Code headers are text comments at the start of procedures that describe what the procedure does, what is passed in, what it returns, any special notes and a brief summary of changes. When you open a function or sub with a code header you immediately know what the code does because it is clearly explained at the top. No more hours of studying the code to figure out how it all fits together.

---

Function RemoveFolderFields(doc As NotesDocument) as Variant
%REM
=========================================================
PURPOSE
This function removes the hidden $FolderRef , $FolderRefId, $FolderRefFlags fields from the doc

PASSED
doc - The current document we are updating

RETURNS
True - We updated the DocFoldersTX field
False - There was no change to the DocFoldersTX field

SPECIAL NOTES
Checks the exisitence of folders that are in $FolderRef field and updates that field with folders that are present in the database.

HISTORY
25 Jun 03        Prasad KVS -         Initial version
12 May 04        Chris Doig -          Removed references to OldDocFoldersTX. Also deleted commented out old code.
=========================================================
%END REM
Your code goes here...

---

Purpose
The purpose paragraph explains why the procedure exists. Well written purpose paragraphs save hours when debugging complex programs.

Passed
On occasion I have opened the code starting with pages of global declarations. Such code is easy to write, but difficult to maintain. When debugging such code you have little idea what is changing those global variables without extensive study of the code. My preference is to avoid passing via global variables, to pass everything though the calling line, and fully describe each item passed. (There is normally no need to describe the variable type, because that is defined in the first line of the procedure. Don't duplicate information - you can never manually keep it up to date.) The passed paragraph describes what is passed into the procedure. This can be another time saver, especially variable names are reused, e.g. exactly which document does doc refer to?

Returns
The RETURNS paragraph explicitly states what the function should return. For example, if the returns paragraph stated the function should return true or false, and something else was returned, you would have a good idea of where to start looking for the bug.

Special Notes
The special notes paragraph describes anything unusual about the code, e.g. why a particular approach was taken. It can also be used for programming notes, e.g."if the folder name is missing, then an error occurs that is not caught by the error handler."

History
The history paragraph is simply a list of dates, programmer names and change summaries. This is particularly useful when projects mover around between several programmers - one can always ask a previous programmer why something was done that way.

An IT department could define a corporate standard that requires all LotusScript code to include code headers, and these headers be maintained. Such a standard helps you climb the CMMI scale. (Of course you have to enforce the standard, or it is worse than useless!) Developers can use something like Teamstudio Snippets (or even a home grown tool) to add this code header to the start of every procedure in LotusScript. You can also configure automated testing tools (e.g. EasyDesignScanner) to check that the code header is at the start of all procedures. Once you have these code headers in place you will have take a significant step towards making your code more maintainable.

When is a name not a name?

This short article makes the case for two corporate software development standards in a Lotus Notes shop. Although aimed specifically at Notes shops, the principles apply to any development that works with user names. These concepts come from hard won experience and observing first hand problems at clients where they had not been implemented.

Answer to the above title question: When a name is in a text field.

Notes names can be in three different formats: abbreviated, canonical or common. If names are stored in text fields, you never can be sure which format was used. Consequently code comparing names in text fields must make six comparisons to ensure all possibilities are covered. Even if you compare @username with a text field you must make three comparisons to cover all possibilities. If you work with lists of names things get out of hand pretty quickly. A far better approach is to mandate a corporate development standard:

Names stored on documents must always be in name fields, and never in text fields. (Note: author and reader fields are also name fields).

This development standard significantly reduces the complexity of any code working with those names. Of course any name stored in a names field can also be used for things like NAB look-up (e.g. for department, phone etc.) group membership and so on. When displaying names they can be converted from canonical to common or abbreviated formats as required, but the underlying name is always canonical.

If users are allowed to manually enter names in a text field you can guarantee that there will be errors. Apart from simple spelling errors, users are faced with things like deciding if there is a period after the middle initial or not, if there is a hyphen or a space in a multi part name and so on. This naturally leads to the next corporate development standard:

Users must always use a look-up for names, and never be able to enter names directly into a names field.

Names fields must be computed (or computed for display etc.) and must use the "Select Names" dialog box or a custom dialog box which updates the field. Although the select names dialog box allows users to enter a name not in the NAB, they very seldom use this option. This development standard significantly improves the quality of the data in a names field.

There is an exception: when the name being added to a field is not in the NAB, e.g. when adding a customer or vendor contact name to a database. Under these circumstances create a "person" doc in the database, and use that person doc for name look-ups. The person doc can also store other information like email address, phone number, company and so on.

Implementing these two development standards reduces the time developers spend working with names fields by simplifying the code behind them. And simplified code has the added bonus of being more reliable, something everybody appreciates.

Thoughts on Managing In-House Software Development Projects

Managing in-house software development is very different from managing software developed for resale. To be sure, there are many things in common, but there are some very significant differences. This article looks at some of the problems unique to managing in-house software, and offers some thoughts on solutions.

The aim of any IT department is to "solve the customer's problem", either by buying software or developing in-house. Usually it's better to buy prepackaged software because this reduces risk and implementation time, and can supply prepackaged expertise you don't have. But large software purchases require an experienced project manager, or you can be the victim of enthusiastic selling. On the other had, there are times when you will undertake in-house software development, for example

• No commercial software is close enough to meeting the requirements, e.g. projects that handle departmental workflows. These are typically small, highly specific projects and there are many of them. Typically they are implemented via a web browser or with the Notes client.
• The project is so small that it would take longer to find and evaluate a commercial product than it would take to develop it in house. This presupposes you have a good developer, good libraries that the developer uses (or a similar project that he is well acquainted with and can copy from) and a rapid application development environment.
• You have developers with a good track record of successful projects, very good understanding of the problem, and of the technology used. Remember that engineering lore states that when a developer gets to the end of a project, then they know how it should have been done.
• The commercial package is ridiculously expensive. I once had a case of implementing a certain feature using Lotus Notes. A commercial company quoted me the equivalent of 3000 hours of developer time for a site license. The developer took some existing code and had a similar solution working in less than 100 hours.

The aim of in-house software development is to produce successful projects in a short a time using as few resources as possible. When it comes to measuring the success of software projects all sorts of numbers are thrown about. They range from studies that claim only 25% of software projects succeed, to one IT director who told me that every single one of his software projects succeeded. So what defines success? Is success meeting requirements, or is it more than this? I would argue that a successful software project has all of the following attributes to some degree:

• The project must be put into production, must meet customer requirements, and must be continuously used by employees.
• The software must be easy to use, and not require extensive training (Reasonable training is acceptable.)
• The software must not frustrate users. Users must find relatively few bugs, and they must not loose data.
• The software must be capable of being extended. When employees start using in-house developed software, it doesn't take long for enhancement requests to arrive. If the project is difficult to maintain and extend, there may be a serious danger of it being only a short term success. So the internal design of a software project is very important.

Now that we have a successful project defined, we need to look at the four elements that go into making a software project successful: Scope, Resources, Time and Quality. Bear in mind that you can never control more than 3 of the 4 elements. Sometimes you can't even control that many!

Scope

A big problem for -in-house software development is project scope. What exactly is going to be done? Project scope should be defined by a Requirements Specification (more in a future article), but often is not. This leaves the way open to scope creep, especially from inexperienced developers who are eager to please. Mr Customer, would you like this feature? It will take no time to add. Usually the answer is yes, and most of the time the developer severely under estimates how long it takes to add. Scope creep is a perennial problem for all software development.

Probably the best way of dealing with scope creep is to push new requests into future releases. You avoid saying no to the customer, yet you are still able to meet the original delivery dates. Frequent small releases allow the customer to steer development as it unfolds.

Resources

When considering resources thoughts naturally turn to outsourcing. While there certainly are projects that can be successfully outsourced, I think that it can easily be a disaster. The main problem is communication between the developers and the customer. It is very important to have the project lead developer talk face to face with the customer. By all means have the developer's manager in meetings etc, but the lead developer must take final responsibility for communication - the manager acts only a facilitator. One on one communication and an immersion the corporate culture give in-house developers a much better chance of developing a successful project.

While offshore developer teams loose out on face to face communication, they also loose out on phone conversations. Usually there is a language or accent barrier, and often a time zone barrier as well. While offshore teams can meet requirements specifications, you can still have a project failure on your hands. I tend to think that offshore development works best where there is a well defined project specification, and continuous communication is not really required.

Whether a team is local or off shore, small, tightly focused teams of excellent coders will be orders of magnitude more successful than larger groups of average coders. Always bear in mind that when you add new people to a project, you increase the communications overhead; there comes a point where adding new coders can actually slow the project down.

In any IT department there tend to be a few large software projects and many small ones. One problem that occurs when you have individual developers working on small projects is they can go off on tangents. These tangents range from a non-optimum architecture though to spending significant time on something that is not project related at all. Here is a lesson I learned the hard way about software architecture...

Many years ago I was managing a developer who was writing software to capture measurement log output of production line machinery (they were making small metal objects on the production line). This software tracked tolerance trends, and if they drifted too far in one direction would shut the line down and prevent scrap from being manufactured. In those days disk space was expensive (I did say this was a long time ago!) and the developer came up with a complicated relational structure designed to reduce disk space. The developer overhead of maintaining this structure was so high that it doomed the project. Looking back I learned several lessons that apply to in-house developed applications:

• As a project manager pay close attention until you are satisfied with the software architecture and the work done.
• Hardware is much cheaper than software development. Always design to reduce software development costs, not hardware. (Also you usually should design for easy of maintenance, and not speed of the code).
• When logging data, you don't need (or even want) a relational structure. The overhead is not worth it.
• The simplest solution is usually the best.

This experience taught me why it is vital that as a project manager you know and understand your developers. If you understand the architecture and can suggest alternatives, you are ahead in the game.

Another tangent is having a developer get side tracked by something that interests them, and loose focus on the required project. While it is important to maintain a developer's interest in a project, discipline is also required. If this gets too far out of hand, the only option may be to let them go, not a pleasant thing to do.

Finally, while priorities do change, as far as possible avoid rapid switching between projects. It seriously reduces a developers effectiveness.

Time

Usually time is the toughest element to manage. One technique is to set frequent, small milestones. This avoids the problem of having a project at 95% done for weeks or months. Then when reality strikes at the last minute it drops back to 50% done.

Another technique is small, frequent releases to production. This  leads to a much higher customer satisfaction than few larger releases. And they allow the customer to better steer the direction of the project.

Always remember to build in contingencies for those unknowns that creep into any project. For example, never budget on a programmer spending more that 75% of their time on their "top" project.

Quality

How well does the software meets the customer's real needs? The problem is a customer sometimes can't articulate those needs very well. Also things come up in a project that nobody can possibly predict at the start.

Good (user) software requires a good interface. Remember that developers are code artists, not graphics artists. A developer can spend weeks tweaking a user interface (UI), and still end up something totally unusable like with red text on a blue background! Contract with an experienced a graphics artist / UI specialist. It is often cheaper, especially when you take the reduced training costs into account. While code reuse is very important, how many people consider UI reuse? Develop a standard user interface theme for all your projects, and free your developers from designing a new UI for every project. Not only do you save developer costs, but you reduce end user training costs as well.

The rate at which the customer finds bugs in production should be minimized. Of course software should include error handling, and part of that error handling must notify the developers when something goes wrong. Log the error to the database, and send an email to the groups responsible for the software. (Note: the error handling in production databases should always use a group, and not names. When people leave the company it is much easier to find all the groups they belonged to and update the names. If names are recorded in the database, these names often don't get updated, and the errors are missed.) When developers are notified by email they will often fix the problem before the end user even notices it. Also, because they don't like being pestered by error notifications, they try to solve the problems that cause the errors in the first place, in effect climbing the CMMI ladder. This is exactly what Microsoft and others are doing when a program crashes and Windows asks if you want to send an error report.

Reducing project risk

There are many articles on reducing project risk on the web, so let me simply summarize a few simple rules of thumb here

• Minimize the unknowns. Go though the project looking for things you don't know, and get rid of them. For example, reduce the number of new technologies, and match developers to the technologies proposed.
• Define the scope of the project well. Minimize scope creep. When new requirements push the scope, put them in a future version.
• Make frequent, small production releases so the customer can steer the development direction. For Lotus Notes development, this could easily be as often as once a week.
• Simplify. To paraphrase Occams Razor: when faced with several similar choices, choose the simplest. Why? Well, if you made a wrong choice and you chose the simplest, it means you throw away the least amount of work.
• Reduce coupling between parts of the project. It is a lot easier to make several little widgets that one big widget. It is interesting to see Microsoft go against this with Exchange 2003 which requires active directory. Linking Active Directory to Exchange has made it so much harder to deploy that two years after the introduction, less than 50% of the customer base has upgraded.

A Few Final Thoughts

We all know the story of the carrot and the stick. Simply put, you are in a much better position when employees want to use the new system, rather than forcing them to use it. And you can reach that heavenly state of project manager bliss by following one simple rule: You must deliver more from the new project that the old way cost. Whether the old way was a manual method or simply an outdated system, the new way must have a reward/cost ration greater than one.

When rolling out a new project, identify the "opinion leaders" amongst the users. If you can get them to endorse the project you are well on your way to a success. Bear in mind that they are not the actual customer, but are members of the user community. Although conventional wisdom says "start with your least critical users", it can be a good idea to roll it out to the opinion leaders first.

• You have the time to hand hold them while bugs are worked out.
• They feel important, part of the team. They build in a commitment to the success of the project.
• When others see the opinion leaders endorsing the project, they tend to follow. The first time I did this, I even had end users asking when they would be upgraded.

Never forget end user training aiming to train at least 80% of your users. It can make or break a project. Of course having decent user help is also important (user help techniques are the subject of a future article).

I hope these thoughts and real world anecdotes give you some good ideas and help you make a success managing in-house software development. projects.

Acknowledgement: I am indebted to Ray Hoving of Ray Hoving Associates for some of the ideas in this article.

Using Version Numbers to Manage Database Designs

Notes templates are marvelously powerful. But that power comes at a cost - templates and database designs must be managed effectively. For any given inhouse developed database, how you do know which version of the design is in production? While this is a problem on servers, it can be a much bigger problem with remote users who replicate databases down to their laptops. When they call the helpdesk, how does the support person know which version of the database is being used? Multiply this by the thousands of databases used at a typical corporate site, mix in a few replication problems and you have a nightmare.

One solution is to use a configuration document to track the database version. This document is updated with the new database version number whenever a new design is pushed into production. With a one-to-one relationship between development and production databases, it is difficult to keep everything in sync. Whith multiple databases from one template it becomes almost impossible. Some people try to track database versions by looking at the date and time on design elements. This is really clumsy and only works on the server;  it fails on a remote laptop if the user doesn't have the designer client available.

How much better it would be to have the design stamped automatically with the template version. To do this you need a design element (as opposed to a document like the configuration document above). The last design step before pushing a new version of the code is to update the version number of the design element. While a page or form could be used, typically a shared field is used because it is more flexible. Since a shared field is a design element, it flows into the production database during a design refresh, like any other design element. This unambiguously identifies the design version being used in production and very neatly solves the problem.

Implementation

In R5 you would use a computed shared field, and set the value of the field the release version, e.g. DocMaster R4.0.40. Release 6.5 moved this idea into core Notes functionality, and you can see an example of it in the mail file. Look at the mail file's Database properties... Design properties (middle tab) and you will see a version number something like 6.5.4 (03/09/2005).  This information comes from a shared field called $TemplateBuild. The example below is from a database called DocMaster. Notice how this production database is based on the master template DocMaster R4 PRD, which is in turn based on the development template DocMaster R4 DEV



If you look at the properties of $TemplateBuild shared field in designer (see below), you will see 3 items on the design element document. (Note: Just like normal documents have items, so design elements have items.) You can access the template version number with a new @function, @TemplateVersion. (Unfortunately there is a bug: @TemplateVersion doesn't work in computed text. You must use a computed for display field).



You can use the new R6 NotesNoteCollection classes to manipulate these item values. I have written a small database Set Template Version (see download link below) that allows you to update these 3 items. Launch the database and follow the instructions in the diagram below. If the $TemplateBuild shared field is not present, it is added to your database.  (Note: if you use Teamstudio CIAO you may get prompted to check out the design element. Select yes, and then use CIAO to check it back in again. This should be the last step before making the new version of the database.) Be aware that the master template does not show  the version information on the design tab of the database properties (because it is not inheriting a design). However, any database that inherits from that template will show the version information on the design tab.



If you launch Set Template Version from the designer client, you can see templates as well as databases when you click the Click to start button. To launch form designer, create a new button on the toolbar, and give the button the formula

@Command([FileOpenDatabase]; "Dev\\Projects\\TemplateVersion\\TemplateVersion.nsf")

Replace the path above with the path to the database on your system. Thanks to Chad Schelfhout for this suggestion, and for pointing out an error which has since been fixed.

Click link to download file
TemplateVersion.zip