Reusability with Standards

In February this year I did a presentation for Teamstudio on Notes Best Practices. Part of that presentation covered standards, and I want to extend an idea on standards by making the following claim: "In the corporate IT world a standard amounts to an agreed upon solution to a recurring problem."

In the software world there is a lot of talk about reusing code. Well, this same thought can be extended (reused?) to go beyond just code. When you create a standard (rule, procedure etc.), you effectively create a solution to a recurring problem. Each time you implement or use that standard, you are taking all the thought & effort that went into creating the standard the first time and reusing it. Let me supply some examples...

* You develop a standard configuration for a Notes client install (or any other software package). Now you company's help desk has just one client install to work with. Every time new help desk people come on board they only have to learn how to support that one client install. Compare this to the situation where there are multiple client installs, each one slightly different.
* You create a standard for your Notes development: all projects must go into under the "Dev\Projects\ProjectName folder, where "ProjectName" is the name of the project. Thus all project files will be grouped in one place. Now, every time a new project is started there is no need to decide where to put the project: just follow the standard. If an old project suddenly needs work, you know exactly where to find it. Compare this to the situation where developers can put projects anywhere they want on a development server, and chaotic mess that results from this approach.


Now, I have often had people say to me "But with all these rules, standards, procedures etc. you are taking away our freedom to be creative". But reality is quite different: standards actually provide greater freedom to be creative. Why? Because standards solve the mundane, recurring problems and leave you free to be creative on the more interesting problems. Do you really want to solve the same problems again and again, or would you rather focus on new problems?

To sum up, creating standards to solve recurring problems and you have reused the effort of solving those problems the first time. While there is a cost to manage standards, the reusability component can lead to significant cost savings. Another benefit is that a standards driven environment is much simpler to manage (i.e. complexity is reduced), and tends to be significantly more reliable. Finally, standards free people from mundane problems, allowing them to focus on more interesting problems. And you though reusability applied only to code...?

More on Corporate Directories

I have worked at a number of companies, and each time this entailed meeting lots of new people. I don't know about you, but sometime I can only remember the first or last name, and sometimes only the nickname e.g. Bob in the corner office. When I need to send an email or look up a phone number, the corporate directories often aren't very helpful.

There is a simple enhancement that can be added to corporate directories to significantly improve their usability, and that is listing people more than once, once by each name. Usually when this is proposed, I get a horrified look, but once people see it and use it, they really appreciate it.

As an example consider Robert Smith, also known as Bob. List him 3 times in the corporate directory, and the people can find him by first, last or nickname. In a small company this makes little difference, but once you are over a 1000 people, it really does make a difference. Suddenly the corporate directory becomes significantly more useful.

Note how Bob Smith appears 3 times, once for each name. That makes it really easy to find him.

This is but one example of a small improvement that adds to the "Continuous Improvement" bottom line.

Drill Down Views in Notes

In The View Nov/Dec 2001 (page15) Damien Katz wrote a short article on a technique for "faking" response documents. (Also see his very interesting articles on the R6 formula engine rewrite and the Formula Language's dirty secret.) This "fake response docs" technique can be used to create drill down lists in Notes. A very useful example of this is a hierarchical corporate directory, showing who reports to whom, and how many direct and indirect reports people have. Use this to drill down from the CEO to the janitor, and see the complete chain of command. Typically this information is updated automatically from the HR system every day, and is a LOT easier to manage and use that the endless out of date Visio diagrams that float around organizations. Recently I posted a screen shot of this type of directory, and Scott Giesbrecht asked me to describe how to do it - so here are the details.

Response documents have $Ref field which contains the UNID of the parent document. If a view's properties are set to "Show response documents in a hierarchy", and $Ref field exists on document "A" containing the UNID of parent document "B", then the view index makes document "A" a response of document "B".

Damien's technique is to use a FakeRef field with the UNID of the intended parent, and then use the view selection formula to set (i.e. fake) $Ref on all documents to the value in the FakeRef field - just for that view. This causes the view to be built with those documents as responses to their parents.

In the sample code posted at the  end of this article, each person document has a FakeRef field called "ManagerUNID" that contains the UNID of their manager. (See Notes 1 & 2 below) The only way I have got this to work is to use the LotusScript "MakeResponse" method of the document - see the code fragment below, which is part of a loop processing all documents. The parent doc is "docManager", and the person document is "doc'. This code runs in an agent that updates the values of the ManagerUNID fields after updated data has been manually entered or imported from the HR system. (See Note 3 below)

Call doc.MakeResponse ( docManager )      'Makes the person doc a response to the manager doc.
Set item = doc.GetFirstItem ( "$Ref" )
Call doc.ReplaceItemValue ( "ManagerUNID", item )      'Creates the FakeRef field
Call doc.RemoveItem ( "$Ref" )      'Removes $Ref so the person doc is no longer a response.
Call doc.Save ( True, True )

Now that evey document has it's parent defined, we are ready to create the drill down view (the Org Chart view in the sample code). To do this we fool the view into thinking that a document has a $Ref field by adding a line to the view's selection formula:

DEFAULT $Ref := ManagerUNID ;         'ManagerUNID is the FakeRef field in the sample code

And, in Damien's words, "This is all it takes". Remember that Notes limits you to 32 levels of response documents, but this is more than adequate for corporate hierarchies.

When you open the sample code, go to People by... Org Chart. Then expand all. You can experiment by adding people to the hierarchy. After adding people run the "Manual Org Chart refresh" agent (Under the View button).

Click link to download file
CorporateDirectory.zip


Note 1
For a document to appear as a response in a view, the FakeRef field (ManagerUNID in this example) MUST contain the hex / binary value of the UNID, and NOT the ASCII version (i.e. @text(@documentUnid) will not work.). The original article in The View was a little unclear here. If a field contains the hex / binary value of a UNID and that field shows on a form, then the contents of the field will appears as a doclink to the parent document. To see this in action, put the $Ref field on a response document form. Then open any response document created with that form in the Notes client. Instead of the UNID of the parent doc showing, you see a doclink to that parent document.

Note 2
You are not limited to just one FakeRef field - you can have several. Each view that uses fake response documents would select the appropriate FakeRef field. This is how one document can have different parents in different views.

Note 3
Heaven is when the HR system exports it's data with canonical names. This makes it trivial to update people's managers, and add the ManagerUNID field. Unfortunately this seldom seems to be the case, so you must find some way of linking manager names from the HR system to the canonical names used by Notes. The next best is when you have unique employee ID numbers, but some HR departments treat these like social security numbers and do their best to hide them. If that happens, you need a routine that somehow uniquely identifies people so that the update agent can put the correct name in the manager field. For more thoughts on the problems of names, see When is a name not a name?.

DocMaster - Single Database Document Manager

When I started working with Notes in 1994, one of the first things I developed was a "Help" database. Over the years this has travelled with me and been used at almost every company I have worked at in one form or another. With input from dozens of people the original Help database has grown into a single database document manager called "DocMaster". A number of people have asked me to post the code, so here it is.

Bear in mind that this is NOT a commercial product; it is unpolished working code with some documentation. The database is both the help file, and the template. Email me with any questions.

DocMaster

Document management systems range from managing papers in a folder up to managing libraries of documents. There are many high end document management systems on the market, for example Domino.Doc or Documentum. If you think of these systems as a library, you can think of DocMaster as a filing cabinet. While there are many libraries in the world, there are many more filing cabinets. And if document collections grow to big for filing cabinets, they can be moved into the larger systems.

DocMaster is a "Single Database Document Manager" that is a place to manage collections of loosely related documents. Although DocMaster is structured like a traditional book, you don't read it as you would read a novel. Rather you read it as you would read a technical manual - typically you find the content you want and then do something with it, e.g. make a decision.

Typical Uses for DocMaster

• Corporate policies, procedures and standards.
• User manuals.
• Help documentation for Notes databases.
• Design notes for in-house software.
• All information on a particular project, e.g. a software upgrade. The next time that software is upgraded, all the notes etc. are in one place.
• All information on a particular piece of equipment, including user manuals, repair notes etc.
• A shared collection of links, pdf docs etc. on a particular subject.
• "Living" documents that often change.
• Meeting agendas and minutes.

DocMaster is easy for end users

• It uses a "Book" metaphor with a Table of Contents, an index, glossary of terms and a FAQ.
• It can use the same 3 pane interface as email, and uses folders as email does.
• It supports full text searching of all content.

DocMaster is easy to work with

• It is simple to set up, and easy to customize and includes tools to customize it for common uses.
• There is security, with document owners, editors, authors and readers.
• Work is tracked as it progresses, and you can easily see what remains.
• Audit trails. Tracks who did what, when and why. You can view or recover earlier  versions of documents.
• Highly customizable sorting: by date (up or down), by title or by doc number.
• Templates to control title format, date, author or many other fields. Templates can include content. Folders can be linked to templates so documents are created with standard settings (e.g. sorting).
• Document counter show total number of documents per folder, person, department etc.
• Tracks the size of documents.
• Any folder can have its own help documents, or one help document can be shared amongst several folders. The folder help document describes the purpose of the folder.

Advanced features

• Use Template documents to create documents with the same initial content.
• Add your own document types.
• Use "shared text" to include the same text in multiple places. Update the shared text once, and it is updated everywhere.

IT Management failures

I was very interested to read comments in Ed Brill's blog on a Notes to MS Exchange conversion. Over the weekend Brian Benz  and I were discussing this, and we both reached the same conclusion: The problem with Notes in this particular instance was not a technical failure, but a management failure. Let me explain. If you look at the Microsoft case study you will see that "employee contact information was stored on multiple, incompatible systems". To quote  from the Microsoft report: Mike Cleary, Director of Strategic Technology at RSM McGladrey stated "There was no unified up-to-date corporate phone book on-line, anywhere." Several observations can be drawn from this:

• Users require a Notes account to use Notes. In this day and age I can't see any employee of a firm like RSM McGladrey not having an email account. So all employees must have been listed in the Domino Directory at the very least. There may have been multiple domains (and therefore multiple Domino Directories). Usually this happens as a result of acquisitions. If that was the case, then the real problem was that IT management had never deemed it important enough to consolidate all user data into one Domino Directory. A classic IT management failure to prioritize projects correctly.

• In any company the HR department owns the people data. When people start or leave, these changes are initiated in HR, and then move out to other departments like Payroll, IT, Facilities etc.. The problem appears to be that there was no system in place to manage people information in the Domino Directory - information like an employee's manager, phone numbers etc. What this indicates is a process failure, or put another way, another IT management failure. IT management didn't see the need to put a process in place to keep people data up to date. Yet clearly there was a need, because it was one of the first things that was done when the MS solution was put in place.

• In any corporation People information is very important. While you can store this information in the Domino Directory, most companies have needs that would mean significant changes to the Domino Directory. For this reason they create a corporate directory in Notes. This often starts out as a phone list and grows from there. A good example that I have used in the past is one where users can see the reporting structure, and drill down. See the image below. 

Example of a corporate directory showing drill down. Note the (partial) business card in the bottom right frame that includes a picture.

• Again, IT management never saw the need for a corporate directory or they would have built one. It is not hard to do, in fact it is often one of the first applications to be build when a new Notes installation goes in. For more power, add Sametime to the mix - a trivial development effort with a huge return. It was only when MS (rightly) pointed out the problem, that IT management realized there was a problem.

Both Brian and I concluded that this company has only done window dressing. The real problems are in IT management and a lack of IT processes. Remember that if an IT process is not documented, it is not an IT process. We both felt that unless there was a significant awakening by IT management, the same problems that existed in Notes would re-appear in the new systems.

One thing that I have always maintained is that when you have problems with Notes (or Exchange, or any other similar system) the real culprit is very seldom technical. The real culprit is that IT management is asleep at the wheel.

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.