Working the project
The right way to begin any project is to plan it. That means taking a decent amount of time to think about what needs to be done, to make lists of requirements and notes about issues, to talk over the effort with customers, to create a project plan, to estimate the time it may take to do the work, and to get all of this approved. Many youthful developers fail to see much value in all that paperwork. They jump right in to begin crafting the prototype. Occasionally, this approach might work, but more often a lack of planning will lead to a lot of rework, missed requirements, and less than happy customers.
Prototyping is of course a great way to prove or present an idea, but do not make the mistake of deploying a prototype. Consider how long it might take to create the production version of your application, and get management's buy-in. Otherwise, you may get stuck supporting a lot of incomplete applications and handling many user complaints.
Work with users, not against them
Some users will tell you exactly what to do and how to do it; others are reluctant to ask for any changes whatsoever. Some developers would rather not speak with customers at all, believing they "know" what the customer needs.
The best circumstance is that in which the developer and the customer work together to advance a project. They share ideas and come to a common understanding of what needs to be done.
Lotus Notes and the Web are very visual environments. As a developer, you need all the help you can get to craft a good-looking and functional application which helps and pleases the customer. Engage with the customer early and often.
It may be difficult to convey in words what a screen will look like or how a workflow will progress. Early in the project, develop a prototype which includes approximations of the forms, pages, views, and other visual elements of the design. Take screenshots and paste those images into an e-mail or a document, and send them along to the customer. Ask for feedback.
If possible, sit with the customer in front of a computer and show him what you want to do. A picture can convey meaning clearly and efficiently, and workflow can be demonstrated really only by trying it out. Do this several times. The customer will share ownership of the project and will offer suggestions to improve the final product. Take notes and take heed. Be a hero.
Identify the champion and other players
With most projects there is one person who will really drive the effort. Identify this champion. He will know the requirements deeply or he will know who knows. He will address resource issues, especially the issue of finding time for customer testing.
Often the most important people are the line staff who will use your application. Find time to discuss with them how they see the new application helping them.
During the planning phase, identify as many people as possible who are interested in the project or who will use the fruits of your labor. Find time to talk with all of them. Your product will be richer and more on-target for the effort.
Don't start without clear requirements
Once in a while you might be required to begin a project without clear, well-written requirements. Resist!
Some customers are notoriously unable to think clearly through and write down what it is they want you to do. They may be willing, but they just do not work that way. Your customer may have an excellent plan in his head, but he just can't get it down on paper.
You may end up writing the specifications yourself and then seeking your customer's approval. So be it. Sit with him, watch what he does on the screen, take notes, and make diagrams. When everything is finally written down, have him sign off on this requirements document. This is the working agreement for the project, and it becomes the arbiter if what you deliver is not what he is expecting.
Understand the budget and timeline; provide an estimate
Requirements identify what the customer wants. You are the resource with the talent who will do whatever needs to be done to satisfy the requirements. But you also must operate within budget and time constraints. How much time, hours or days or weeks, are you authorized to work on this project? Are there any hard deadlines which must be met?
Most likely, before work begins, you will be asked to provide a time estimate for your work on the project. Study the requirements in detail and make notes. Estimate how long each task is likely to take. Be as realistic as possible with each estimate.
If you are familiar with the application, then the project will move along more rapidly. If you must discover the application learn about it from scratch then time must be allotted to that effort as well.
Include time in your overall estimate for the following work:
Planning and setup (time to create development and test databases)
Discovery (familiarization with the current design, if there is one)
Development (all the fun stuff)
Developer testing (once the coding is done)
Working with customers to test the changes (including code corrections)
End-user training
Rollover to production
Documentation (including suggestions for the next release)
Estimate the work in as detailed a manner as possible, and then roll-up the details into a grand total. Some people suggest adding a contingency factor, perhaps 10-20%, for unknowns. Remember, this is the actual time on the task that you anticipate will be required. It does not take into account non-project commitments, vacations, sick time, and so on.
Avoid scope creep
As the project moves forward, the customer will likely ask for additional features or changes that were not included in the original requirements document. It is tempting to agree to make changes, but such scope creep can be costly in terms of time and money. On the other hand, if the changes are sensible, consider including them. Discuss all such changes with the formal project coordinator or with your manager.
Assume that all Notes applications will be web-enabled in the future
Many times the Web is the first target for a new deployment, but sometimes a customer does not request web-enablement for an application. All well and good, but barring some unexpected international catastrophe, the trend towards moving applications to the Web should continue into the foreseeable future. So assume that a request will come along eventually to make that new "Notes only" application accessible from the Web. And assume also that older Notes applications, if they are not replaced, will in time be web-enabled as well.
With this in mind, it makes sense to focus on using only techniques that are directly transferable to the Web or that have highly comparable correlates. So as you develop, don't rely on techniques (like Environment variables and @Picklist) that have no direct counterpart for web applications. Check the Designer Help files for the lists of features that do and do not work on the Web. Keep this list handy.
Familiarize yourself with an unknown design
If the task at hand involves enhancing or web-enabling an existing application, then one of your first tasks is to familiarize yourself with the application as it exists already. If there is any existing documentation, read it. If not, you will have to undertake the discovery process on your own.
Start by taking a copy of the design. If there is an archived authoritative design, request a copy of it. If there is no authoritative design, don't trust any copies you may find on the development or staging servers. Previous developers may have left pre-production changes lying around that never made it to production before they moved onto something else. Ask for Editor access to the production database and take the design from there.
Examine the agents in the current design. If any of them are enabled and scheduled, make notes about which ones are enabled and then disable them. It may well be that some of these agents send e-mail notifications to people as part of a workflow. Other agents may automatically download or upload data to other databases. Until you know what the agents do, disable them.
Determine if there is a version or release designation for the production design. If not, assign it one. Then set the designation for the new version you are about to craft (for example, "Version 1.3").
Create a development database from the production design on your development server. You will be accessing this database with a web browser, so placing it on a server provides you with a more realistic view of how the application is accessed (or will be accessed) by your customers.
If you can copy documents from production without compromising security, then do so. Otherwise, copy some documents from another non-production database or simply create your own documents with the current design.
Examine the Access Control List (ACL) of the production database. Take note of which groups are listed and what privileges and roles each is assigned. Adjust the ACL of your development database if necessary to assure you have Manager access to it. This level of access enables you to modify the ACL if your design changes require it.
Open the application with Notes and look around. Read the About and Using documents. Look to see if there is any other internal documentation which may be helpful in understanding the design. Open the views and a document or two. Look over the agents.
Open your web browser and create a bookmark to the development database. Try to open it. If the database fails to open properly, re-open it with Notes and look for a "configuration" view and document of some sort. A configuration document or application profile may require changes before the database will open properly on the Web perhaps the configuration document lists the wrong server name or database file path. Make changes and try again. Once you have the application open in a browser, explore it. Begin to think about what you must change in order to implement the requested changes.
Assess an existing application for web enablement
A customer may inquire about web-enabling an existing Notes application. As a first step you may be called upon to assess the condition of the application as it currently exists and to provide a work estimate for the uplift.
The first task, assessing the application as it currently exists, might best be undertaken by a quality assurance tester or by a power user who will "think like a user" rather than like a developer. On the other hand, if someone like that is not available, you may be tasked to perform the assessment.
Think like a user
Understanding an application from a user's perspective is an important part of designing a good application. Take off your developer's hat for a time, and do not think about how this or that feature might be coded. Experience the application. Is the navigation intuitive? Do the forms look good? Is it clear what needs to be done?
Make at least two passes through the application before drafting a proposal. During the first pass access the application with Notes to understand what the application is supposed to do. Reviewing the application with Notes provides a baseline of expectations and may also uncover anomalies which warrant fixing.
Then access the application from the Web to see how it already compares (favorably or unfavorably) to the Notes version. Start at the beginning when the application first launches and proceed in an orderly fashion through all the features. Make notes. Take screenshots.
Think like a developer
Once the initial functional and UI assessment takes shape, go back through the application with Designer to get some ideas about what needs to be done to correct the application and to get it ready for the Web.
Especially if the application is several years old, there may be many opportunities to spruce it up by making relatively modest changes that won't break the bank and that may greatly improve customer satisfaction. After all, older "out of the box" Domino applications can look dated compared to contemporary websites and well-crafted web applications. Here are some cosmetic, "low hanging fruits" to consider. Some of these issues are covered in more depth in later chapters:
Change to web-oriented fonts like Verdana or Tahoma, rather than fonts which are more suitable to the printed page
Add accent color
Adjust field alignment and layout
Convert styling to CSS (Cascading Style Sheets) for maximum flexibility and styling options
Standardize the size and color of buttons
Try using tabbed tables
Style Action Bar buttons or remove the Action Bar altogether
Use some visually interesting HTML, like the
<fieldset>and<legend>tags
Write a report
The end product of the assessment should be a report with plenty of screenshots which demonstrate the current state of the design. Here is a simple outline which can be used for such an assessment report:
Title Page
Business owner name and contact information
Developer name and contact information
Table of Contents
Summary
Purpose of the application
Summary table (information about the application: name, owner, location, size, replication, indexing)
General recommendations
Notes
Screenshot upon opening the application
Testing notes
Errors encountered
Deficiencies noted
Other observations
Web Browser
Screenshot upon opening the application
Testing notes
Errors encountered
Deficiencies noted
Other observations
Developer Recommendations
Each observation and recommendation can be assigned a specific number and title using the form in this example.
APP-01: There is no obvious way to create a new document
The assessment report can be used in discussions with the customer to illustrate how features currently work (or do not work) on the Web. Screenshots can help to set customer expectations about how much work is required.
The outcome of the general assessment would be a decision whether or not to allocate resources for refreshing and upgrading the Domino application.
Keep an issues log
Issues arise during the course of development, and even during routine maintenance tasks. There are decisions to make, problems to investigate, code to fix, tests to run, and documents to write. Typically, there are too many items to keep in your head, and jotting notes on scraps of paper, frankly, does not work well when there are many issues or when several people are involved in a project.
Keep an active log of items in a spreadsheet, in Team Room documents, or even in outline form with a word processor. Read and prioritize this list regularly. Review items with your project team, manager, and customer as appropriate. The issues log will help to keep you focused and moving forward. Fewer issues will fall through the cracks.
Track information about each issue in a consistent way. Keep enough information about each item to answer questions that arise, but do not overdo it. Create the issues log which you need for your project. Here are a few key items which might be tracked. Add to or subtract from this list as appropriate to your needs:
Item number
Title or subject
Status
Short description
Date reported
Who reported
Dependencies
Assigned developer
Assigned tester
Comments
Improve the application under the covers
Customers are concerned with look and feel and with functionality. These are aspects of an application which they can see and about which they may have opinions or demands. They assume that applications will perform well and flawlessly, and therefore considerations like good response time and effective error trapping are unlikely to make it to their requirements list.
However, these are things which developers should care about in great detail. A good looking, feature-rich application which is slow or which hangs, or displays many error messages, such an application is a failure.
Here are some things to consider. Each of these topics is elaborated in later chapters.
Enhance performance wherever possible
Web applications require significantly more server and network resources than do comparable Notes applications. Reduce this performance hit by using strategies known to help. For example, use Ajax calls to refresh a pick list rather than re-compute the entire form with a round-trip to the server. Compile a list of performance techniques and implement them.
Add error trapping
Nothing is more annoying than seeing an HTTP 500 error displayed in a browser. This and related error messages are generic; they provide little value in determining what went wrong. Aggravated, the user calls the Help Desk to complain, a ticket is issued, the developer interrupts his current task to attend to the user's problem.
Thorough testing will uncover the majority of error conditions, but never all of them. Again, compile a list of error handling techniques and implement them in your applications.
Add diagnostic and repair aids
Views that display data in ways that simplify troubleshooting can be invaluable when tracking down obscure data issues. Small agents that repair various problems within documents can also be added. It might be best to allow these tools to be seen and used only by the application administrators and developers.
Provide the customer with a summary of changes
Prior to or coincident with rolling a new application or a design upgrade to production, prepare a somewhat detailed Summary of Changes for the new version or release. In this document, identify for each change the following things:
An identifier and a title
A statement of the customer requirement fulfilled by the change
The design elements that were added or modified
Screenshots before and after if appropriate
Other notes
Test that were run to verify the change
The Summary of Changes is the final report of the project, a clear statement of what was done. You may wish to include a list of suggestions for the next design upgrade.
