A fresh start is invigorating, a chance to look forward with high expectations and new resolve. It's a time to put into practice all the lessons you have learned and to put behind you the issues and problems which previously bogged you down. Take advantage of every fresh start. Look forward to and accept every new challenge and opportunity.
Especially when starting a new job, it is important to take stock of your skills, both technical and non-technical. If you succeeded wildly at your last job or project, then hooray for you! Do it again! But if you fell short in some ways, resolve to do better.
The topics in this chapter address the human and organizational context within which you will develop your Domino applications. Most of these suggestions are relatively non-technical, as they deal with how you might organize yourself and your time and how you might work more effectively with your customers. Topics focus on these key issues:
Preparing yourself as a Domino developer
The importance of using standards and guidelines
Planning your work
Handling a development project
Documenting your design
A craftsman is only as good as his tools, and in a very real sense, you are your tools. To remain capable and versatile, you should commit to the life-long task of continually acquiring knowledge and skills people-skills as well as technical skills.
As you begin your work on a new project, keep in mind the larger picture. This new project will be followed by others. One polished application will lead to another. One happy and satisfied customer will spread the word about how good you are.
While you browse the Web, gather ideas about what makes web pages look good. Great websites should inspire you. Inspect the layout, the use of images and color, and the navigational strategies. If you see an interesting control, peek under the covers and take notes about how it was coded. But be sensitive to intellectual property and copyright laws not everything published on the Web is free.
In particular, collect links to public websites that use Domino and show it to good advantage. Relatively speaking, only a smaller number of public-facing websites are served by Domino. But browse around; you will find hundreds of them in short order. This collection of websites can become a marketing and public relations tool for you as you sell your ideas to your customers.
Too often Domino web applications crafted in the past were functional, but not pretty. That might have been okay ten years ago, but no longer. Today's customers expect the same kind of functionality from your applications that they see elsewhere on the Web. And there really is no reason why you can't provide it to them.
Take some time and build yourself a small application to hold the links. Eventually, roll this application to the Web so that the links can be shared readily with customers and others who are interested.
In this sample Domino Websites application, details about each website are stored in a separate document. The blue hotspots link to views which display lists of Commercial, Consultants, Government, and Other Sites. With sufficient privileges to the database, a user can add, edit, and delete these documents with the Notes client or with a browser.
 |
Honing your skills by doing is essential. The more applications you build and the more time you spend on this work, the better you should become at it. Experience is a great teacher.
But you do not have time to figure everything out yourself. So you must read and study what others have done, which is especially easy today with a fast connection to the Internet. Set aside some time every week (or each day if you can swing it) and graze the web landscape.
Commit yourself to preparing for, taking, and passing certification exams in Lotus Notes / Domino application development. If possible work through the Administrator exams as well. Effortful and extensive preparation should make it easier to pass the exams the first time. More importantly, preparation for the exams will broaden your understanding of Domino and teach you about features and techniques that you might not otherwise stumble upon by yourself.
And, of course, holding this certificate looks good on the resume.
Experienced developers rely on Domino Help. Be aware that there are separate help databases for each of the clients: Notes, Administrator, and Designer.
 |
The Lotus Domino Designer 8 Help database contains over 9,000 documents. In it, you will find extensive information about features, language syntax, classes, limits, errors, tips, and code examples.
The code examples can be particularly useful. If you find some code that looks just like what you need, simply copy it into your application, and then modify it as necessary.
Especially if you are new to Domino, spend enough time with Help to be comfortable with where things are and how to find information on specific topics. The Contents view organizes the information like a book, by general subject area. Use the Index if you know what you are looking for the syntax of a specific @ function, for example. Use the Search feature when you are not quite sure for what you are looking. Beware of searching too broadly. Search for the term "web" and you will find over a thousand documents!
Once you are comfortable with Designer Help, try Designer's context sensitive help, which is invoked by opening or highlighting a design element and then pressing F1. Display forms in the Work pane and press F1 help on designing forms displays. Select a tab in a Properties box and press F1 help on that tab displays, and so on.
Designer provides basic editing for text, so for the most part, you can develop applications without using external editors. However, dedicated editors for HTML, JavaScript, Java, and CSS will provide you with conveniences such as syntax checking, color coding, validation, and ready-made functions which may appeal to you. If you develop code in an external editor, you will have to import the files as resources into your application or copy/paste the text into appropriate locations in your design.
You can reasonably get on without external text editors, but learning to use an image editor may be well worth the time it takes, especially if you do not have access to a graphic designer or a library of images. Almost any image editor will do as long as it saves images as JPEG or GIF files. (Designer can accommodate other graphic types, but JPEG and GIF files are natively compatible with the Web.) Although it may take some effort to learn, the open source program GIMP is a no-cost, feature-rich image editor. Find more information at the GIMP website: http://www.gimp.org.
In this book, except where noted, examples rely on only the native capabilities of Designer.
New ideas for solving problems constantly present themselves. But introducing a new, untried technique into an existing application may result in many more problems than it solves due to unintended consequences and side-effects.
Create one or more sandbox applications in which to try out new ideas. Constraining new development this way facilitates isolating and resolving problems specifically related to the new technique. And if, at the end of the day, the technique does not live up to its promise, then nothing needs to be removed from the real application design on which you are working.
Solutions discovered or invented for one application inevitably find their way into other applications. Code snippets, strategies, and even entire agents are often reused to save development time and effort.
Keeping track of such ideas may be difficult over a period of years, especially if you work on dozens of applications or move from job to job. It might be inappropriate (ethically or legally) to keep personal copies of designs created for previous employers without permission, but it is certainly reasonable to keep detailed personal notes in one form or another. The tools are readily available: paper notebook, flash drive, optical disk.
Keep your notes organized and periodically review items in your cookbook. Revise and annotate. Include variations and caveats. As it is impossible to remember in detail all the code you will ever write, you will find your notes to be an invaluable resource.
As a Notes developer, you should always have access to the Notes and Designer clients, so creating a personal document library or a simple Notes application is certainly an option. You can use the standard Lotus Document Library template or you can simply create your own application with whatever features work for you.
One database might contain notes and descriptions. A second database might contain working examples of many techniques a private code library if you will.
The Web is a wonderful repository of ideas. Consider keeping a website (blog or Wiki) on which you can post code and ideas that may be helpful to others. Of course this approach may entail some expense and extra effort, but it is also a great way to contribute to the development community. And if you are a freelance consultant, it is also a way to market your skills.
Alternatively, consider contributing ideas to existing websites with blog entries or even entire development projects.
Over time, the language of Notes and Domino changes, as do the tools. At one time, the Domino Directory was called the Name and Address Book or NAB. The file that contains design elements and documents was called a database and is now referred to as an application. In Designer, the Design Pane became the Application Navigator. Of course, you will come across references that use the older language and some developers who continue to use deprecated terms out of habit or stubbornness.
Be alert for these changes of terms and the definitions which go with them. Be mindful of the old names, but use contemporary and correct vocabulary, just as you should use contemporary development techniques.
Domino applications intended to be accessed with a web browser can take advantage of many contemporary web technologies like Ajax, CSS, and XML. In fact, support for these standards has been included in Domino for many years. As web technologies evolve, so does Domino.
So pay attention to non-Domino web technologies and strategies. Web-enabled Domino applications should be crafted using the best web programming practices.
Application development is part engineering and part art. Building some pieces of an application is fairly routine, while other aspects call for inventiveness and creativity.
Domino caters to developers to some extent by enabling applications to be built with any of the several programming languages. It also supports many web technologies which can be pieced together in an unlimited number of ways. This flexibility enables programmers to work the way they want to work. But this same flexibility makes it all too easy to ignore organizational standards.
Standardizing applications makes it easier to develop new ones since reusable components may already exist. And if applications look and operate in a similar manner, then users of new applications will need less training and will be more willing to use them.
If your organization has written web development guidelines, find out what they are and try to embrace them in your own applications. The set of web applications deployed by your organization is probably much larger than just the Domino applications. If they exist, these development guidelines and standards define stylistic and functional commonality that your organization determined to be beneficial. Someone above your pay grade approved those standards, so abide by them!
Web application development guidelines can provide several benefits. They promote an organizational identity or brand through a common look and feel. They improve the effectiveness and the usability of web applications as a whole by standardizing how features and functions operate. And from a developer's point of view, they speed the deployment of new applications and simplify the maintenance and enhancement of existing ones.
If your organization has no written standards, consider discussing this issue with management. Consider taking on the task yourself.
The number of specific development standards can easily number in the hundreds, depending upon how detailed they are. Whoever determines these standards must understand to some extent the entire universe of options, and then must select those guidelines which make sense and which can be implemented within the existing development environment. Many guidelines turn out to be "nice to have" suggestions that are not practical to implement within the confines of budget and project deadlines.
Development guidelines can be classified roughly into three kinds:
Usability guidelines
Stylistic guidelines
Mechanical or process guidelines
Guidelines that address the usability of an application or website concern themselves with issues of effectiveness, efficiency, learnability, and overall user satisfaction. How well does this application achieve its goals? How easy is it to learn to use? How well do users like it? Usability influences how willing people are to use an application, which can have a dramatic impact on whether they choose your solution or go somewhere else for assistance.
Usability guidelines focus on what things make a website easy to use from the end user's point of view. Examples of usability considerations include the following:
Content organization
Headings and labels
Page and form layout
Features and functions
Accessibility
Navigation
Images
Explore this topic in greater detail. One online reference which you might consider reviewing is the http://usability.gov website maintained by the U.S. Department of Health and Human Services.
The Guidelines documents at this site were written based on the extensive research. They can serve as a good starting point for understanding usability issues.
Guidelines which address style concern themselves with issues of look and feel, and sometimes function. An organization's font preferences and color palette can be identified. Layouts and menu styles can be defined. Acceptable logos and images can be specified, as can boilerplate text for Copyright, Privacy, and other notices. Very specific guidelines might address issues such as whether or not to underline links or how wide margins should be.
Beyond simply specifying preferences, an organization might codify style requirements into common style sheets. The guidelines would then provide information about how to link to and incorporate those style sheets into applications. Details such as style class names for headings and labels would be included.
Guidelines which address issues of coding and application deployment can be extensive and no small task to gather together.
Because Domino web applications can include so many different technologies, coding guidelines could address various options, including the use of these design tools:
Other guidelines might specify requirements for the following design aspects:
The About and Using documents
Element naming conventions
Form and page layout
Navigation
E-mail notifications
Data import and extract
Context sensitive help
Agent error handling
Security and access control
Still other guidelines might concern themselves with the general way in which applications are designed, tested, and rolled into production:
How development work is requested and prioritized
How applications are named and sponsored
The use of templates
The use of shared code and resource libraries
The use of roles
The use and management of Domino groups
Application signing
Replication
Testing and approval
Migration to production
Documentation and user training
Some developers might find coding and process guidelines to be onerous and overly constraining. Inevitably, there will be requests for exceptions to the rules, so organizations must be prepared to deal with the issues of exceptions and non-compliance.
Clearly, an extensive effort is required to compile standards and guidelines that are appropriate to application development within the context of a specific organization. Additional effort will be required periodically to review, update, and reapprove those guidelines.
Organizations should consider creating common repositories of reusable objects. The most obvious kinds of libraries (not surprisingly supported natively by Designer) would contain standard design elements such as:
Images
Java code
JavaScript code
LotusScript code
Style sheets
Images can be organized into common types as follows:
Arrows and lines
Banners and logos
Buttons
Patterns
Photos
Squares and other common shapes
Watermarks
Other repositories might include standard or approved "boilerplate" text:
Copyright notice
Disclaimers and caveats
Error messages
Privacy notice
Common repositories enable developers to work more rapidly and to create products which conform to organizational standards. Organizational management must address the following issues:
Who will create and maintain the repositories?
What process will be used to approve, add, and deprecate repository objects?
Will applications be reviewed to assure the use of the approved objects?
How will developers (especially new developers) be informed about the repositories and how to use them?
Common repositories, like development standards in general, can seriously boost productivity, but they also require ongoing maintenance and commitment. If your organization has such repositories, learn to use them. If no such collections yet exist, speak to management about instituting common repositories for approved design resources.
Volumes have been written about planning, and even more volumes have been written about how to become and stay organized. Here are just a few simple ideas that can be enormously powerful in keeping you personally on task.
When you are young and brilliant, your mind might be as sharp as a tack and your memory as long as the Great Wall of China. But as your responsibilities increase, as your projects become larger, as you attend more meetings and deal with more customers as you get older your infallible memory will become fallible.
Take notes. Write things down. Some people prefer to use a laptop or PDA. Personally, after many years of trying several methods, I've come to appreciate the simple notebook. I jot notes all day long at my desk, in the car, at a meeting, in bed at night. It contains my list of tasks, my key contacts, notes from meetings, to-do lists, and timestamps. It is my work-life in a compact, lightweight, versatile package and it works without electricity.
It is a simple fact that people who make lists of things they must do, tend to get more things done. This is true on a personal level as well as on the job.
Start each day by making a list of tasks you will work on, meetings you will attend, and phone calls you must make. Keep that list nearby and refer to it often. If things come up during the day, add them to your to-do list. As you finish an item, check it off or scratch it out.
At the end of the day, review what you achieved and what is still undone. Create a new to-do list for the next day. Prioritize each item either in terms of how important it is to do or in terms of when you will do it. This simple activity will help you focus, and when you focus, you accomplish more.
If you are not used to working with to-do lists, it will take some self-discipline. You might also consider creating weekly, monthly, quarterly, or annual to-do lists as well. As you plan each day, consult the lists which deal with the longer timeframes and incorporate all relevant items on the daily to-do. The adage "Plan the work and work the plan" can be fulfilled easily with the simple to-do list.
You should maintain a current list of all your active and pending projects, tasks, and commitments. Each item should include a rough estimate of how long it takes or will take, when you might start and finish it, and who the key contacts are for each item.
Inevitably, you will be asked to undertake new tasks, join committees, attend meetings, and perform services which take time. People easily become overbooked because, with an eagerness to please or to start something new, they simply do not estimate well how much time tasks take to do. Keeping a list of projects and tasks to which you can refer will help you and your boss allocate your time more effectively.
Developers and other technicians are often loath to spend time documenting, especially writing progress reports to managers. Managers, on the other hand, really do need to understand what their employees are doing. Well-informed managers can make better decisions when authorizing new work, prioritizing current tasks, handling contrary customers, reporting accomplishments to their managers, and requesting budget for the coming year.
As a developer, you should submit a summary of your work on a regular basis. Your organization may have a prescribed format for this activity. If not, here is a simple outline for weekly e-mail which can work satisfactorily:
Highlights from this week
Tasks for next week
Issues and other items
Pending projects
Add bulleted items in each section. Be concise, clear, and plain-spoken. Your goal is to convey a sense of your activities and progress to your (possibly non-technical) manager. Send this summary to him or to a project leader at the end of each work week when the information is fresh. Do not embellish, don't minimize. Use this report also to help plan the week ahead.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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
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
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.
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:
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.
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.
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.
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.
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.
Application documentation provides a more detailed record of what was done and why. Months or years later, you will appreciate such notes when you revisit the code to make modifications. And it is certainly a professional courtesy to other developers to provide insight about why some aspect of an application works the way it does.
There may be an organizational requirement to document applications in a certain way, and if so, do so. Consider going beyond the minimum requirements. In any case, leave tracks.
If you took a programming class somewhere along the way, you were told to add comments to your code. This admonition is still valid today. Comment complex or obscure code in a plain way so that future developers can more readily grasp the associated technical implementation.
Every agent should include a summary of what it does, how it is called, what calls it makes, and how and when it was revised. A complex @ formula or JavaScript function should likewise include statements describing what it does. Sometimes hidden text placed on forms also can be helpful.
Developers generally write too little documentation, and what is written is often found in documents external to the Notes application itself. Months or years later, no one can find the external documentation. A new developer begins discovery of the application all over again.
Instead of writing external documents, use the Page design element to record developer documentation. Maintain a consistent naming scheme, and identify them as 'Developer Notes' in the Comment field on the Page Info tab of Page Properties. Keep these pages within the design template. They will take little space, and they will always be there for the next developer.
In addition to the application owner and developer contact information, an application's About document often includes release notes. Details about a specific release can be included in a separate collapsible section that lists changed elements.
Consider organizing release notes in an outline form. Here is a sample:
Summary of Changes
Developer(s)
Database as a whole
Framesets
Pages
Forms, and so on
Add numbered or bulleted items in each section with specific information about the changed design elements.
Word processing documents, spreadsheets, presentations, and so on created during the course of a project can be imported into the design template as file resources. In this way, relevant external documents are never lost and remain with the design for future reference.
Application discovery is a great time to make notes about how an application works. If little or no useful user-oriented documentation exists, consider saving notes and screenshots on pages in a separate user help database. Work out a simple, common navigational menu for each page. Once the collection of pages is complete, deploy it for customer use as well as your own.
Application development is about more than mastering a set of technical skills. It is also about you, the developer, and your customers. It involves strategies for staying organized, gathering information and requirements, estimating how long work will take, and reporting progress. It also involves going the extra mile to enhance performance, harden applications against unexpected failures, and documenting what you did and why. This chapter has provided general suggestions which may be applied to any development project.
