Get in on the discussion in our Open IT Forum.

I have suggested five components of an application documentation set. This configuration provides a structured organization, covers a wide range of clients, and minimizes overlap. Not every application will require all the components.

Now, I will describe the components in more detail.

The Overview component is your marketing pitch. It describes your product in high-level detail, identifies key application elements and tells your prospective customers why this product is the best one for them. I once was responsible for maintaining a large banking application and fortunately, the overview documentation provided me with information which made the task less terrifying. It described the various time dependent functions (daily, weekly, monthly, year-end, backups, etc.), inputs and outputs.

Think of this as the glossy brochure you read before beginning your search for a new automobile. It quickly will identify key features of the automobile which you can then compare with your needs.

The Operational component is your will and testament. It states how the application is to be managed after you (or your team) are gone. The ideal goal is to turn over the day-to-day operation of the application to another group without your close involvement. This information can be enhanced over time. I used this vehicle to document application issues and resolutions. If changes to the system were required, this was also noted. If the application crashed, there should be documentation for attempting a resolution (or only call the on-duty support staff), perhaps manually resetting control items (dates, cycle numbers, cheque numbers, etc.), voiding/deleting output information (such as files, cheques, etc.) or rerunning the application. This last option could entail manual over-rides to input and output files, reports, etc. As issues arise over time, the documented resolutions may help resolve late night issues.

This documentation should also describe the relationship of data files and the various application components. As and example, the daily function might consist of enabling the online files by 5:00 AM and initializing the log files. The nightly function could state that the online component is to be stopped by 9:00 PM, the backups to be completed by 11:00 PM and sent off-site, the aging function to be completed by 2:00 AM, the verification function to be completed by 3:00 AM, all client reports/information to be processed and distributed by 6:30 AM. As stated earlier, any operational issues should be documented in this component.

The Programmer component is probably the heart of this documentation. It contains not only the code for the applications, scripts, tables, etc. but also the modification history of the application. It shows approved changes, what components were changed for each revision, and if you’re lucky, it might even provide a backout solution. This is the bible for application support staff.

The Customer component is the ‘how to’ resource for the users of the application, and tells them how to use the application in the most effective manner. It should be created by function (how to create a data record, how to delete a record, how to modify a data record, how to select data for reports, how to manage various control elements, etc.). This document should be written with the client in mind – how will they use the system. There are several formats that can be used, and I am fan of a 3 column tabular version. The 3 columns contain a sequence number, an action column and a results column. The integer sequence number indicates the function (such as the login process is 1.0), The action column indicates what the client must do to achieve the result or what the function is, and the results column describes what will occur.

I personally don’t like the SELECT, CLICK, CLICK, etc. approach, because the client may not fully understand the process, they just follow the rules. Another technique, which initially is nice, is to use screen images to instruct clients. This is valid until a change to the graphical interface is made, thus possibly making the documentation confusing or incorrect. The documentation should be designed to minimize revisions when modifications are made to the application.

The following attempts to illustrate a login scenario:

STEP ACTION RESULT

1.0 LOGIN
1.1 Select APP, Press ENTER Invokes login screen from standard corporate menu
Go to STEP 1.3
1.2 Press: CNTL+ALT+PGDN This invokes the stand alone login screen
1.3 Login screen appears
1.3.1 Enter your account id This is your id for this application
1.3.2 TAB to password field
1.3.3 Enter your account password Field contents not displayed
1.3.4 Press ENTER key Valid account/password invokes APP
1.3.4.1 Invalid password prompts for another attempt
1.3.4.2 Go to 1.3.1 After 5 invalid attempts, account is suspended for 1 hour
1.3.4.3 Contact HELP desk Account activation

The Data Dictionary is the hub that holds these components together. Unfortunately, I have not found a product that works to my satisfaction. This repository should contain the data elements for the all applications, along with definitions, formats, edit/verification rules, etc. There would be links identifying the applications, data files, data bases, etc. using the elements. This would help ensure that the data elements are used correctly. The data elements could have alias names which could be used by different programming languages. Just think how easier application support would be if every program used the same set of data element names?

I have worked on several projects where the data elements were defined before the source code was developed. It took a while to get the data elements correct (you don’t need to be 100% complete), but the programs were developed much faster and with fewer errors. In one project, we developed month-end profit ratios for manufacturing plants. There were over 200 reports and each program used the common data element definitions. It is now relatively easy to trace data elements to programs, files, reports, and data bases. All system clients use the same terminology, know the data element definitions and what they represent – thus avoiding some misunderstandings.

This documentation model is not perfect. I feel it can be used as a basis to develop better documentation. After all, if you have a problem with an application, where do you turn to for help? If the documentation is poor, no matter how wonderful the application, it is bound to fail. Just like the chain, it is as strong as the weakest link.

Mike Malesevich has been an IT professional for over 30 years, working with IBM mainframes and UNIX. From application developer, tech support to operations support analyst and security admin, Malesevich has made his rounds in information technology.

Get in on the discussion in our Open IT Forum.

While documentation doesn’t necessarily make the world go ’round, it certainly keeps it spinning neatly on its axis when trouble arises. If you’re providing a product or service, you should be providing your customers with accurate information that allows them to effectively use and maintain that product, which translates into accurate and thorough documentation.

When an IT project begins, there is normally time allocated for documentation purposes, however, as development issues crop up, time is often siphoned out of the documentation components and allocated elsewhere.

Normally, documentation should be developed during the project, and reflects the changes that arise. At the project completion, it should be a simple process of assembling all the accumulated documentation, arranging it in a useful order and publishing it. This is the perfect world – but we don’t work in one.  Too often, documentation is developed during the ‘last week’ of a project, and is handed to the person who has the least amount of work left, which is usually a junior team member.

Often, I find there is too much documentation. Some authors feel that the documentation should reflect the size of the project. Many times, the documentation is not well organized, it’s just slapped together with the hope that the client/user can figure out where the required information is buried. Without a well planned structure, there is a high incidence of overlap, duplication, and just excess information.

Some major problems with documentation are that it is a static, entirely manual process, and frequently there is no incentive to keep it current, or the time frame for updating the documentation properly is too short.

The only true documentation is the executed code and the corresponding source listings.

What characteristics should documentation have?

• It should be an integral part of any development effort.
• It should start at the beginning of the project and continue during the project lifespan.
• It should reflect the project elements, not a summary of the evolved project.
• It should be dynamic, changes should be easily incorporated.
• It should be structured and modular in composition, targeting specific audiences.

In my opinion, this can be achieved by organizing the documentation into 5 components:
1. Overview
2. Operation
3. Programmer
4. Customer
5. Data Dictionary

Each component is targeted at a specific audience, with little overlap of information. Each component is self-contained, modular and can be used to reinforce another component. If a component is not required, then don’t create it.

The Overview component provides a high-level introduction of the product, and can be thought of as the marketing literature. It describes the functions and features as well as why the customer should buy your product. This component can be developed by an individual with marketing experience.

The Operation component contains the information needed by those individuals who are responsible for keeping the system functioning properly. This could be a formal operations staff, remote office workers, anyone who needs to look after the system. Some of this information would describe how to start/stop the application, availability, problem resolution processes, day to day processing, report distribution, verification of processing, backups, etc.  This document should be created by the development and operations staff.

The Programmer component contains the source application code, compiled listings, logic flow processing, pseudo code, and other information needed to maintain and trouble-shoot the system. This document would be the responsibility of the development staff (programmers, analysts, etc.)

The Customer component has all the information needed to successfully use the application. It has procedures for inputting, extracting and modifying information. Problem resolution procedures are included and often developed as incidents occur. This should be the user’s bible and should be developed by the customer base, analysts, and development staff.

The key component is the Data Dictionary.  It contains the information (meta-data – data about data) referenced by the other components. It contains data element definitions, file and record lay-outs, application logic definitions, report descriptions, process flow, sub-system relationships, etc. Theoretically, all the data elements would be created first in the data dictionary (data bases, files, data elements, data relationships, function definitions, reports, etc.), then propagated out to the various entities that need them (source code, security rules, etc.). Unfortunately, there are not many effective data dictionaries on the market and most of this is added to the programmer component documentation.

By separating the documentation, you are providing authors with specific places to deposit their information. Not everything will fall neatly into one of these components, you will need to convince yourself where the best fit is.

As an example, suppose you were trying to find the format of the birth-date element, you would look in the Data Dictionary or perhaps the source code. If you were entering this data element on a screen, you would look at the Customer documentation. In all cases the official definition would be in the data dictionary, and this would be propagated out to the required components.  If a change to this data element was needed (expand birth-date year from 2 to 4 digits), it would start in the Data Dictionary and flow outward, thus making this change easier.

The next article will deal with each of these components in more detail.

Mike Malesevich has been an IT professional for over 30 years, working with IBM mainframes and UNIX. From application developer, tech support to operations support analyst and security admin, Malesevich has made his rounds in information technology.

As covered wagons made their way along the Oregon Trail headed for the gold fields of California or the lush timber of Oregon, whenever the wagon wheels started to squeak, the wagon driver knew it was time to stop and grease the squeaking wheel-before it failed.  Along the trail there wasn’t the equivalent of a Firestone or a Goodyear to get a replacement.  A failed wheel was inconvenient at best or a matter of life and death at worst.

Originally, I think this phrase implied that problems should be fixed as soon as they are identified.  But over the last 100 plus years, the term has become associated with “the person who complains the loudest gets what they want.”

Organizations that rely on a “first come, first served” approach to making project decisions, or worse, the “whoever screams the loudest” approach, might get projects out the door-however are they the right projects.

For most organizations, keeping people busy isn’t the challenge, it’s keeping people busy doing the right things.  Evaluating every potential project based upon pre-determined metrics ensures that the business value of every project will be evaluated objectively, regardless of the stakeholder.  Making knee-jerk reactions to the demands of influential stakeholders can be expensive.  Spending valuable resources working on projects that provide minimal value can be catastrophic.

Establishing a process that requires every potential project to demonstrate its value based upon pre-determined criteria gives executives confidence that they are making well-informed project decisions.  Some of the important questions to ask when evaluating any project should include:

1.     What are the high-level objectives of the project? It’s not uncommon for a project to morph into something very different from what was originally intended.  Specifically identifying the goals of every project help project teams, sponsors, and stakeholders stay on track.

2.    What are the estimated costs of the project-and the anticipated rewards? Without the answer to these questions, it becomes difficult to determine if the potential project will provide any business value, let alone the greatest value.

3.    Does the potential project align with the mission, vision, and values of the organization? Individual projects must represent the execution of strategic direction if the desired result is to maximize every dollar spent in the pursuit of the greatest ROI.

4.    What are the risks associated with pursuing the project under consideration? If potential project risks can be identified and evaluated while in the consideration process, actions can be taken to mitigate risk and increase the probability of success.

In a perfect world, every potential project that provided business value would be pursued.  However, anyone doing project-based work understands that there always seems to be more work than there is time or resources to do it. Which is why establishing a method for evaluating every potential project is so important.  Measuring and considering every potential project based upon merit is the first step to effectively managing demand-and an important component to project success.

Should the squeaky wheel always get the grease? Probably not.

Project management is incredibly simple until you actually have to do it, which is why books, seminars and other aids abound. I’d heard of T-Shirt Sizing before, where team members are asked to help estimate and prioritize project elements using relative measures, rather than guessing the absolute time or manpower needed. Yvette Francino uncovered another project estimation technique, Project management poker:

Planning Poker is a technique where each team member use cards with a range of numbers to estimate effort. Typically the numbers do not progress incrementally, but are more spread apart, the higher they get. The Fibonacci series (0, 1, 2, 3, 5, 8, 13, 21, …) can be used for this. The reasoning behind this is that the larger the numbers get, the more uncertainty there is.  Cohn gave us each a deck of cards and had us do an exercise in which we were given several tasks and then work in teams to estimate those tasks using the cards. If we didn’t agree on the first pass, we would explain our reasoning and vote again. In all cases, we were able to reach consensus quickly.  Cohn even has made a free planning poker tool available for distributed agile teams.

Yvette has posted some videos that more fully explain why poker planning works, and there’s even a free tool to try it with your team online. While that tool is specific for Agile development teams, I would love to hear if you think, or any other project estimation techniques, are useful in your department when plotting out major projects.

9. Speak different languages. Early on, Sesame Street emphasized the importance of learning foreign languages, even if it was just the basics, such as the Count learning to say uno to diez in Spanish. More now than ever, it’s critical that IT learns to speak in business terms to explain value, as recent guest blogger  Claude Roeltgen noted. So-called soft skills can save a career, and really, it’s just a matter of saying what you need and what you can do in the right language. [kml_flashembed movie="http://www.youtube.com/v/Jg3WY2Sgxtw" width="425" height="350" wmode="transparent" /]

8. Learn to count. Or better yet, teach others to count. Just as our dear friend The Count spent painstaking hours teaching others to count from one to ten (in English and beyond!), IT must teach the rest of the business how IT enables profits and performance. And if you let others do the counting? Expect IT to become a cost center, with aggressive accounting for every dollar and annual budget fights.

7. Be wary of strangers. Sesame Street wins over adult fans with copious guest stars, running the gamut of celebrities, athletes and musicians. But these guests are introduced by trusted adults on the show, and viewers learn that while you shouldn’t fear people different than you, you also shouldn’t give them your complete trust until they’ve earned it. What are your security policies, and what do you do to ensure that temporary workers or outside consultants have what they need — but nothing else?

6. It’s not (always) easy being green. Kermit the Frog was right: No matter often people tout the benefits of “going green,” cutting costs while saving energy can be full of trade-offs. There’s always new equipment to buy, new processes to manage, and while there may be a green revolution, there’s a premium to be paid for leading that charge. On the other hand, Kermit did get the girl and in many cases the energy savings from a comprehensive, business-savvy “green” policy can bring home the bacon at the end of the day.

5. Keep it simple. Forget the ABC’s: At the end of the day, an episode of Sesame Street was brought to you by a single letter. What are your “letter” projects you can quickly point to as a tangible, easily understandable success? Did you cut spending by 15%? Boost productivity measurably by 7% with the new Intranet? Keep the take home lesson for your boss simple so he knows to give you the ‘A’ you deserve.

4. Learn from your mistakes. Big Bird once sang that “everyone makes mistakes.” Projects fail,  breaches occur, budgets run over and schedules run behind. What matters is how bad you let things fail, and what you can takeaway for the next time. Do you know how to spot a project failure? And are you ready to let go,  move on and clean up the mess, without letting your emotional investment get the best of you? If not, maybe give Big Bird’s song one more listen, take a deep breath and bite the bullet.

3. Learn to share. Yes, you can do it all on your own, but why when you can share the work? Ellen DeGeneres shared headphones with Elmo, and you can share your work with users. There are big steps like allowing users to define file permissions, but even milder approaches like crowd-sourced troubleshooting and training, where users help other users, can save IT time, money and headaches. But just like with Ellen and Elmo, it might take some experimentation to find the right mix.

2. Teamwork. Just like the Sesame Street classic says, “Cooperation makes it happen.”  It’s true, and IT is essential to making it happen, either by leading the way on effectively using communications tools or simply in being a team player with other departments, both inside and outside of IT.

1. Even grouches have their place. I’ve written about how overly aggressive personalities can actually hurt productivity, but Sesame Street offers up a great counterpoint: It all takes all types to make a neighborhood. Everyone from Oscar the Grouch to The Count to Big Bird to Cookie Monster has (or at least had) their place, and there’s a good chance both the Grouches and cheerleaders have their useful places in your organization, too, whether it’s a cold dose of realism on how effective an over-hyped project will actually be or the willingness to look for opportunity amid cutbacks and concern.

Bonus: Change with the times, places and people. Sesame Street isn’t the same around the world, focusing on “Unity through Diversity” in Indonesia and cooperation and sharing in Northern Ireland editions. So much has changed, and so much more is now known, in the world of children’s programming that re-released episodes are for adults only:

“These early Sesame Street episodes are intended for grownups and may not suit the needs of today’s preschool child,” the warning reads.

Is your organization able to shift with the times and culture? Does your IT have the same policies in Japan as it does in the United States and Brazil? If so, maybe it’s time to take a closer look and find where improvements can be made.

What lessons did you learn from Sesame Street? Let me know in the comments, on Twitter or at Michael@ITKnowledgeExchange.com.

Diby’s 6 points could prove quite handy when doing a perished project’s port-mortem, and Dilby even offers in depth looks at each of the categories:

• Intent Failure – Occurs when the project doesn’t bring enough addedvalue or capability to beat down the obstacles inherent throughout the process.  This suggests the original intent of the project was flawed from the beginning.
• Sponsor Failure – Occurs when the person heading up the project is not actively engaged and/or does not have the authority to make decisions critical to project success.
• Design and Definition/Scope Failure – Occurs when the scope is not clearly defined, so the project team is unclear on deliverables.
• Project Discipline Failure – Occurs when process/project methodology is allowed to lapse so that the mitigation factors inherent in the process are never used.
• Supplier/Vendor Failure – Occurs when the structure of supplier /vendor relationships doesn’t allow for communication and adjustments.

Communications Failure – Occurs when communications are infrequent or honest discussion of project problems and issues are avoided.

But while hindsight is a glorious 20/20, what would be really useful is a system for flagging these problems down before the latest initiative, with your name stamped boldly at the top, goes ingloriously awry.

More on IT project failures:

• Preventing Project Failures, Michiko Diby’s blog
• Michael Krigsman’s take on Diby’s six types of IT project failure
• 10 innovative ways to become a “lousy” project manager
• The Perils, Pitfalls, and Pluses of Project Management

]]> http://itknowledgeexchange.techtarget.com/IT-watch-blog/6-reasons-your-it-project-was-derailed/feed/ 0