C H A P T E R  8

Documentation

Documentation has a bad reputation among software developers. Just mention “documentation,” and those of us who were raised on traditional waterfall software project methods remember weighty requirements documents, followed by detailed design documents, followed by lengthy reviews and signoff documents, all before a line of code was written. We recall long meetings, flipping through reams of paper (the poor trees!), and the inevitable loss of enthusiasm for the project before coding even began. If we were lucky, funding (or interest) ran out before we were required to produce technical manuals, end-user manuals, operational manuals, administration manuals, and more at the completion of the coding cycle. No wonder documentation has a bad reputation for many of us aging developers—we wrote more documentation than code. Thank goodness the Agile world has left that voluminous mode of communication behind in favor of Agile documentation.

Agile documentation is nothing more or less than the application of Agile principles to document aspects of your software project, when and only when it is essential to do so. Agile documentation is clear, succinct, efficient, and just enough. Agile documentation can take many forms, the key factors being that it must add value and it must not cost more to produce than that value. The purpose of this chapter is to describe the principles of Agile documentation and suggest how to apply those principles to your APEX projects.

This chapter opens with an overview of the principles of Agile documentation and discusses when, how, and in what form to produce valuable artifacts that support your working software. The second part of the chapter recommends standards and habits to develop for producing Agile documentation specific to your APEX projects.

Agile Documentation

One of the core values of the Agile Manifesto is “ working software over comprehensive documentation.” So, you say, why a whole chapter on documentation? Haven’t we left that behind? While yes, the main goal is to produce working software, no, we `1. Depending on your project, it is likely that documentation in some form will be required. The difference is, in Agile software development, documentation is an essential supplement, not the driving force or the proof of completion of your project.

There is wealth of material on the topic of Agile documentation, readily available through the Agile Alliance or a simple web search, or through the reference section for this chapter. It is beyond the scope of this text to repeat that information here. It is recommended that the reader consult the chapter references for more in-depth Agile documentation material. For the scope of Agile and APEX development, the subject can be summarized in this simple statement:

Do as little as possible, as efficiently as possible, as late as possible.

To be even more succinct, the whole gist of Agile documentation can be condensed to these two words: just enough. Write just enough, and no more. Period.

Characteristics of Agile Documentation

Documentation is communication. Communication may take many forms. With today’s technology, communication is more often by electronic means such as e-mail, text messaging, images, charts, and documents than by the traditional Word documents or snail mail of a decade ago.

We have instant messaging, web cams, video conferencing, Net Meeting, and Web-Ex as common meeting mediums. Preserve those communications, and we have documentation of our meetings and the information exchanged, perhaps including decisions made. We also have prepared videos, podcasts, hand-drawn diagrams, screenshots, all online instead of printed, and of course the more traditional spreadsheets, tables, and text-on-page documents. Whiteboard contents, sticky notes, a photograph of those sticky notes on a wall—all of these are valid forms of communication that may in fact document some facet of your software project. The information exchanged, how it is communicated, whether it needs to be preserved, and, if so, in what format are unique to each project. I personally consider comments in code, including APEX developer comments (the text that you should be entering in the Comments attribute of your page and region objects), as valid forms of documentation. Code and developer comments are communication of how your code (or your APEX module) works. What better place to communicate what your code is doing than in your code, where the next developer, or yourself, will see it and learn (presuming they read it!).

Before planning or producing documentation for your project, consider these factors:

• What is the least amount of information that needs to be communicated?
• What is the optimal format for that communication?
• What is the cost to produce and maintain that communication?

As Little As Possible

In Agile software methods, it is not necessary to record and preserve every fact about a software development project. It is essential to record information that is not otherwise known that is critical to the end goal of working software. If how to use a particular page of your APEX application is not intuitively obvious, communication of how to use that interface must be provided. This communication may be made in one or more of several forms: as an online help page, online tooltips on page items, an online how-to video, an online step-by-step how-to document, or an annotated user manual. Exactly what needs to be documented, and in which form of communication to provide it are decisions best made by the Agile team during the development process, following the rules and guidelines of the project and the parameters defined by the project manager.

Valid reasons to document generally fall into these categories:

• To communicate with an external group
• It is required by your stakeholders or regulatory agency.
• To define an interface with another system
• To validate a theory or thought process
• To remember

Documentation may be required to communicate during development, particularly if your team is not located together. In this case more than any other, the printed page is most costly, due to changing and evolving needs, and is the least effective. How long does it take to produce the documentation, vs. how many developers stop to read it? Consider more effective, less costly forms of communication, including screenshots, diagrams, charts, whiteboards, NetMeeting or WebEx sessions (recorded or not), or the plain old phone call—all viable means of communication when it is not possible to walk down the hall and talk face-to-face. Document only what is essential to communicate the point, in the least costly way possible.

It may be essential to produce documentation that is mandated by your organization, or by regulatory agencies in your industry. There may be an enterprise-wide requirement to produce a formal document using a corporate template, and to have all wording approved by a central communications board. In these cases, ensure the document is indeed required—that it conveys essential, valuable information about your project—and plan to deliver only and exactly what is required. You may have to produce a document, but does it have to be 12 pages, or 2? If a particular document does not add value to your project, then whenever possible get permission to not produce that document, and get that permission in writing. Be prepared to justify your request by providing the hours (and cost) to produce the documentation vs. the value added to your project (none, if you are requesting to not produce it!). In many cases, the cost vs. value added argument suffices to get a requirement waived. When you are required to complete documentation templates, the recommendation is to complete only those sections of the template that apply to your project. Again be prepared to cite the cost vs. value added evidence for sections that you are omitting, and get permission to do so in writing.

When your software is part of a contract between one system and another, documentation of the interface between the two is required. For example, if your work product is part of an API or a web service, it is necessary to document the parameters of your software in sufficient detail for others to use it. If you are consuming a web service, or accepting input data, you will need to document the expected format of the web service request or your input data format.

Sometimes you just need to put it in writing, to clarify an idea or confirm that all avenues of thought are covered. Sometimes an idea that seems clear in your mind is not so simple when drawn out on paper. Sometimes different team members envision the same idea differently, and drawing, diagraming, or otherwise documenting the concepts allows the team to work toward consensus.

Sometimes documentation is simply necessary to account for infallible memory. Do you remember details of code you wrote last year? I don’t, unless I have notes to jog my memory. Through the years, I have developed a system of coding standards, comments, and notes that when combined serve to remind me of unique aspects or unusual features of a project months and even years later. This documentation, shared with others, means the why and how of my code are not lost, and it is maintainable.

If any of the foregoing reasons apply, documentation in some form will be required. Having established that documentation is communication, and there are many avenues for it, what is the best way to deliver documentation in an Agile APEX project?

As Efficiently As Possible

Once you have discerned exactly what to document, the guiding question is, what is the optimal form to most effectively communicate that information, at the least cost to the project? Figure 8-1 compares the effectiveness of various modes of communication vs. richness of content.

Figure 8-1 clearly illustrates that face-to-face communication in front of a whiteboard (or similar medium) is the most effective mode of communication, while paper documentation is the least effective. Documentation options in all forms are lower on the scale than all of the modeling, less concrete options. A page of text, printed or online, is still our least effective form of communication. We should use it sparingly. We should produce text-on-page documentation only when we have to—when other forms of communication do not suffice for the particular communication need.

Notice that text messaging is missing from the chart. I suspect it will be added in future releases. My personal feeling is that text messaging, while instantaneous, falls on the low end of this scale because it lacks the verbal and visual clues that make face-to-face communication so effective. I find it interesting, and sad, that text messages and instant messages are replacing e-mails, which have replaced phone calls. Yes, text messages and e-mails document an issue, but they have no richness of content, and are therefore, in my opinion, less desirable forms of communication, even when laced with emoticons.

As Late As Possible

All documents have a cost incurred to produce and maintain them. That cost to produce and maintain must be less than the value added. Documenting as late in the development cycle as possible means that fewer changes are required to keep the material up to date.

Models, diagrams, charts, drawings, and text that are part of the design evolution are best formalized only when they are stable. Stable does not necessary mean finalized, but it does mean stable. On a recent Agile project, three persons in a room drew, discussed, redrew, scribbled on, and, when satisfied they were “done,” made a Visio diagram of their model to present to management. Scribbled-on drawings were fine for the development team, but not for the management meeting, where they were seeking approval to move forward. Several weeks later, the team hit a new requirement that did not fit their original model. They regrouped around the Visio model, talked out the options, and made new scribbles on the documented model until they were satisfied their revised model was correct. Then they prototyped to confirm their corrections worked, and only then adjusted their Visio model to present the updated case to management. Freehand drawings and scribbles were faster for the team during the process. Visio quickly documented the results in a format acceptable to management once the model was stable. The team formalized only at stable points in the process. The use of Visio told the story in a single picture that took one person only a half-hour to create. A Word document to formally describe the model would have taken much longer to write, much longer to present, and much longer for management to read (if they did), all incurring greater cost for the project.

As late as possible may mean never. In the foregoing example, if there was no need to present to management, the freehand drawings, with scribbles, would have sufficed as documentation of the model, and in that case, no Visio. If a feature is eliminated as your project evolves, the need to document goes away as well. A recent project involved a simple file upload. The uploaded file had to be in a specific format. The upload process entailed a series of validations on the uploaded records. A brief online document was planned to document the process for future users. The document was required prior to the move to production. In QA testing, the upload proved too slow. Eventually the upload was replaced by a database link—no user interaction at all, no need for the upload interface, and no documentation required. Had the development team built that documentation page in time for QA, it too would have been obsolete.

As late as possible does not always mean never. Do not mistake “as late as possible” to mean “If I procrastinate long enough I won’t have to do it at all.” That might happen, but the more likely reality is that the more you procrastinate, the less you are likely to have to do, which incurs less cost for your project.

Just Enough

Agile documents are clear and concise, and include just enough information, but no more. How much is “just enough”? It depends on your audience, on your stakeholders, on your contract, on your subject matter, and on your particular situation. “Just enough” for the purpose of specifying parameters for a module that controls O-ring manufacturing for the space shuttle is going to include more details than “just enough” for how to use your company’s online trip report approval software. Use common sense to gauge how much is just enough in your situation. Know your subject matter, know your stakeholders, and know your industry and contractual requirements. Communicate only the essential information in the clearest, most concise format possible.

Remember that producing documentation takes developers away from producing working code—the main goal of the Agile project. Producing any more than needed, because it’s nice to have, because it looks good, or for any other reason, keeps them away from coding longer. It’s not worth it!

Rules for Writing

Regardless of the type of documentation—APEX help page, developer comment, item help, spreadsheet, diagram, or formal text document—I strongly recommend the following guidelines. On purpose, these are the same suggestions for publishing individual rules and guidelines in Chapter 7. Consistency across all areas of a project is nice—it promotes predictability and comfortability and can actually be habitforming.

• Use short and concise active voice sentences.
• Write in full sentences: capitalize the first word, and place a period at the end of each sentence.
• Use clear, meaningful, full-word names for all objects.
• Use screenshots and diagrams generously.
• Consider using APEX’s websheet tools to author a web-based document.
• Ensure accuracy. Few things will discourage developers from taking advantage of good documentation so much as simple lack of accuracy.

The following sections cover each of these guidelines in more detail. Follow them, and your writing will be clear and concise, and above all useful.

Active Voice and Complete Sentences

Short, concise, active sentences are easy to read, easy to understand, and easy to write. Yes, even developers can learn to write short, clear, direct, complete sentences to communicate. Pseudo-code is for code; complete sentences are for documentation. Keep the purpose and the audience of the document in mind, and provide no more and no less information than necessary. In writing documentation, you are not creating a novel; you are communicating facts about your software. Write just enough, and then stop.

Clear and Full-Word Names

The use of clear, full-word, meaningful names for all objects promotes self-documenting code at all levels, for all stakeholders. Using EMPLOYEE versus EMP removes any ambiguity (did he mean EMPty or Elector Magnetic Particle?). Meaningful names make it easier to find things when debugging. Less technical documentation is required because the code itself is clear.

Images and Diagrams

A picture conveys a thousand words, and a screenshot saves typing even more. A video does even better, if you have video capture programs available. Screenshots easily convey exactly what a page in your application looks like. There is no need to describe every item on every page, or form layout or report features, if it can all be conveyed in a single screenshot. Most computers have some sort of image capture utility. When you have it, use it. Then supplement the screenshots with just enough text, using full words, to communicate the essential information.

APEX Websheets

When a team is building an APEX project, the use of APEX websheets makes sense for a number of reasons, outlined in Chapter 7. Using the Links region of the Team Development home page as a central location for all project documents, including the Rules and Guidelines document, is a wise idea. If your team is not APEX-centric, a link to an APEX websheet can be included anywhere a link is valid. At a minimum, consider adopting some form of online, central document management system, to minimize communication time, maximize communication efficiency, and maximize the return on investment of your documentation.

By now you may be back to thinking about documentation as text on a page, printed or online. Let me stress again that the point of documentation is communication, and that communication can take many forms. Charts, diagrams, sketches, tooltips, online tutorials, comments in code, and videos are all forms of communication that may be acceptable for a given purpose. Traditional textbooks and hard-copy user manuals are now replaced by context-sensitive tooltips, help pages, and tutorials. Step-by-step tutorials—how-to documents—are now being replaced by YouTube videos. Take advantage of all forms of communication when choosing the most effective one for your task. Remember that not all forms of documentation are required for your project. Create only what is necessary, in the most efficient mode possible.

Be sure to match the document form with the audience. A freehand sketch of the program’s workflow may be sufficient for the development team, but it is not sufficient for display to end users or management. Turn that freehand drawing into a Visio diagram and include it as an image on a help page, and you now have a non-text, effective document for your audience, at less cost than the equivalent text to describe the process in words. Use the least costly, most effective mode of communication possible to convey your information, and then stop. Just enough is enough.

Accuracy

For documentation to be of value—worth the resources you invested in its development—it needs to be clear, concise, just enough, and accurate. Inaccurate documentation in any form is worse than useless, because of the lost hours incurred in figuring out it is wrong, then in figuring out just how wrong. Besides losing resources, you lose credibility, which is much harder to reclaim. When considering the cost of documentation, include the cost of maintaining it.

Documentation Within APEX

APEX affords many avenues for incorporating documentation into your application as it is developed. The Team Development tool, when enabled for your project, tracks features, milestones, to-dos, and progress. The Application Builder contains attributes for help text and developer comments on most elements. The Application Builder Utilities offer numerous reports of your application development progress, automatically. This is a lot of information about the development activities in your application, all at no cost to your project.

If you develop wisely, use Team Development, and avail yourself of the wealth of information in the Application Builder Utilities reports, the need for additional documentation will be minimal. That certainly fits our Agile documentation criteria of doing as little as possible, as efficiently as possible. As late as possible doesn’t really apply for these built-in utilities, as the reason to build documentation late is to minimize cost. As there is no cost to build or maintain the APEX tools and utilities, the only investment is in using them to discern which reports provide the most useful metrics for your particular project.

APEX Utilities

While not documentation in the traditional sense, the APEX Utilities are a valuable set of reports that document various aspects of the development of your applications. Figure 8-2 shows the APEX application Utilities home page. The help region says it all: these utilities summarize information across the application and provide access to useful tools.

Figure 8-2. APEX Application Utilities

The data contained in the Utilities reports are all automatically collected by APEX. There is no hiding from the APEX engine—if, as a developer, you spend all day updating a page in your pet project when you were supposed to be working in another application, the APEX Utilities will rat you out, in the Change History and Recently Updated Pages reports. Curious as to the latest changes in app 107, which worked fine last week, until Teddy the Temp made a fix? Check out the Recently Updated Pages report. Need an overall health check of your application? Check out the suggestions in the Advisor. It is not within the scope of this text to describe each of these utilities, but I do recommend that all team members get familiar with them as a mode of mining information about your project, all for no added cost. That definitely fits our criteria of “as little as possible.”

Team Development

The APEX Team Development tool, when used, is one way to document features, milestones, releases, to-dos, bugs, feedback, follow-up actions, and developer progress. See Chapter 7 for more complete information on Team Development features, practical use, and how it supports the core Agile values and principles.

Team Development is an ideal way to document the process and progress of an Agile development project, because it is so well integrated with the APEX application development process. The Team Development repository is exposed to APEX users as interactive reports. Developers, team leaders, and other stakeholders can customize reports to meet their needs. Developers can track their sprint backlog, or check the to-dos on the current sprint. Team leaders can monitor the sprint backlog, or prepare progress reports for business teams or other stakeholders. This simple, customizable documentation of your team development process is available with relatively little investment.

The customizable Team Development report certainly meets the criteria for Agile documentation—the report can be customized to show just enough information for the intended audience. The cost to produce the report is minimal—only the investment of entries in the Team Development interface. The only maintenance is to continue with normal entries into the milestones, releases, to-dos, and bugs interfaces. These entries would need to be recorded somewhere else, if not in Team Development, to track project progress. The wealth of valuable information output relative to the data input investment makes this lightweight form of project management a very valuable, flexible Agile documentation tool.

Standards

Standards for building an application should include standards for naming objects, standards for writing help text (which could start as database comments), developer comments, and code comments, and standards for building navigational elements. I believe that all of these are documentation—communication of some important fact about your application—even when that fact is consistency.

Here are some standards to consider that assist in documenting your application in the most agile, efficient way possible:

• Define a naming convention for pages, page items, and regions.
• Define naming and numbering conventions for pages and page groups.
• Define a naming convention for database tables and columns.
• Define naming and numbering conventions for Team Development entries.
• Define a strategy for entering feedback, developer and end-user. Developer feedback can be useful in tracking thought processes that need collaboration. Add additional feedback categories as needed.
• Define a strategy for application navigation that includes when and where to use (or not use) list menus, tabs, breadcrumbs, and navigation bar entries. Use a common convention across all of your applications.
• Mandate use of User Interface Defaults and the Attribute Dictionary to define defaults, including item help, for columns and field items.
• Define a strategy for item help that includes when and where to use tooltips, labels with help, and/or help pages.
• Define a strategy for using dynamic actions.
• Define a policy for using plug-ins.
• When additional documents are essential, define a template that includes a look-and-feel that is common to your application.
• Define a central location for all additional documents (in any form), such as the Links page in Team Development (for internal use) or links off of a help page (in your application).

The list could go on, but this is a good start. Your standards will of course vary to suit your organizational and application requirements.

Creating and applying standards for naming conventions and the use of help and comments mean that a good portion of your application is documented as it is developed. How many of us incorporate help text in every item on every form? If not, why not? For the investment of the seconds it takes to type (or cut/paste) text into a field, your end user has help for that field—as opposed to some developer (and it should be you) going back to do it later, or, worse, creating a separate document for the help. It is simply more efficient to enter the help text along the way, if it is not picked up from the Attribute Dictionary.

Creating and applying standards for look-and-feel, help format, and navigational elements mean that end users are more comfortable with your application because it is familiar—“Oh, yes, it works just like that other application that I already know how to use.” Remember how you felt when Microsoft came out with the ribbon for its Office products? Now imagine if MS Word had a ribbon, and MS Excel had a detachable toolbar, and MS PowerPoint had a series of list menus, and MS Access used context-sensitive pop-up menus. There would have been a revolt! Standards for look-and-feel aspects promote consistency. Consistency promotes end-user comfortability and confidence. And that means you have less to document, because there is less new material to communicate to your users.

Standards in your APEX application should include defining User Interface Defaults and populating the Attribute Dictionary for all tables, including help text for page items. User Interface Defaults define default attributes for columns in a table that, if present, are used by the Application Builder Create Form and Report wizards. The benefit of employing User Interface Defaults is twofold: consistency (again) and saved development time. The cost incurred is the time to complete the User Interface Defaults for a table in the first place. The cost saved is the time not spent in manually setting attributes for each item in your form or report on subsequent create form or report actions. The invested cost is more than regained the second time you create a form or report on that table. Many developers skip defining User Interface Defaults because of the setup time. I guarantee that most of those developers are mumbling under their breath the second or third time they manually enter attribute settings for the same table—they should have used the User Interface Defaults.

Standards should also be specified for Team Development entries: naming and entering milestones, releases, features, and bugs. Milestones and releases need defined naming or numbering schemes. Features and bugs need standards for priority assignment, weight assessment, and scheduling. Naming, numbering, and priority schemes are useful only if everyone on the team uses the same conventions.

Standards for feedback—when to add it and in what category to record it in—should be included to ensure the correct feedback information is captured and forwarded to the appropriate persons. Standards for the use of dynamic actions promote consistent page behavior and development practices. Standards for the use of plug-ins promote reuse of common features and minimize repetition of code.

Standards are essential for the development team, the stakeholders, and those who maintain the application to understand what is there, why, and how long it took to produce. Standards are also important because they promote consistency, which is in itself a form of self-documentation that aids team leaders, developers, stakeholders, and end users. There is value added in not having to go back and add information—or worse, create separate documentation. As Agile developers, we are always looking for ways to do as little documentation as possible. The use of standards helps us toward that end.

Habits

A habit is a recurrent, often unconscious pattern of behavior that is acquired through frequent repetition. My recommendation is to apply standards religiously, until they become habits.

Some habits to develop in your APEX development that promote the concepts of Agile documentation include the following:

• Use User interface Defaults.
• Use the Attribute Dictionary (import table column defaults for reuse on similar column names).
• Write developer comments consistently, using a consistent format per your organization’s standards.
• Include item help as you build items, using a consistent format per your organization’s standards.
• Include page help as you complete each page, using a consistent format per your organization’s standards.
• Use Team Development, if enabled for your project.
• Use feedback where enabled for your project.

Note that most of these habits are in the list of standards that I recommend in the foregoing section. When standards become habits, they happen as a natural part of development and generally incur less effort. Less effort means less cost. That’s what we want.

User Interface Defaults

User Interface Defaults allow you to specify defaults for regions and items. Using common user interface defaults promotes consistency, which makes your application easier to use, and likely to require less supporting documentation.

As of APEX 4, User Interface Defaults exist in two categories: the Table Dictionary and the Attribute Dictionary. The Table Dictionary contains defaults by table, for all the columns of the table. Table Dictionary defaults are usually initialized from the database definition and then customized as desired. The Attribute Dictionary, new in APEX 4, allows specification of defaults based on column names, and includes synonym features so that all columns of that name—no matter the source—will be assigned the same attributes. Attribute Dictionary settings may be initialized or updated from page items and report columns. You can also use the Attribute Dictionary to update page item and report column settings.

One process flow for populating the User Interface Defaults dictionaries is to use the Table Dictionary Synchronize function to populate defaults for tables and columns in your schema, and then migrate these settings to the Attribute Dictionary using the Attribute Dictionary Migration task. Migrating settings from the Table Dictionary to the Attribute Dictionary removes them from the Table Dictionary. Next, create some forms and reports, adjust the settings of various items as desired, and then update the Attribute Dictionary based on your customized page item and report column settings. Once your Attribute Dictionary is loaded, you can also use the Attribute Dictionary to update page items and report columns. How you initially populate and use the Table and Attribute Dictionaries is up to you. Note that defaults in the Table Dictionary will override any defined within the Attribute Dictionary, so be mindful to remove tables from the Table Dictionary when you have superseded those settings with Attribute Dictionary entries.

For example, synchronizing the Table Dictionary at the start of a project will set the default data types and populate all table and column comments. Figure 8-3 illustrates using the Table Dictionary Synchronize function. This is an easy way to load all your help text, since your data definition standards dictate that you have comments defined on your tables and columns. Once you have populated the Table Dictionary, when you create forms and reports, the table column attributes may be used by the APEX Create wizards. Be sure to select the Use User Interface Defaults option in the wizard—this ensures the attributes you have just set will get used.

Figure 8-3. APEX User Interface Defaults, synchronizing the Table Dictionary with the schema

Figure 8-4 shows the Use User Interface Defaults option on the Create Form and Report wizard. If this option is not selected, your User Interface Defaults will not be applied.

Once you have created a form or report, the Attribute Dictionary detects when there are settings on the page that could be either loaded into the Attribute Dictionary, or updated on the page based on the settings in the Attribute Dictionary. Keeping the dictionary attributes synchronized with your page item and report column settings promotes a common look-and-feel throughout your application. This makes it easier for users to follow and easier for developers to maintain, and reduces the amount of supporting documentation that may be required. When your look-and-feel standards are included as User Interface Defaults, APEX actually helps you apply them throughout your application.

One way to easily bring existing database comments into the Attribute Dictionary is to create a simple form based on the table, and then update the Attribute Dictionary using the “Review items for update of the Attribute Dictionary” option and selecting the columns to update.

Figure 8-5 displays the Attribute Dictionary dashboard for a given APEX page, in this case, a form where we have 11 items for which the page attributes differ from the dictionary attributes.

Figure 8-4. Selecting the Use User Interface Defaults option in the Form and Report wizard

Figure 8-5. APEX Attribute Dictionary, using the “Review items for update of the Attribute Dictionary” option

Figure 8-6 shows the Update Attribute Dictionary interface. On this page, select the attributes to be added to the Attribute Dictionary, and click Update Attribute Dictionary. These attributes will now be applied in the next use of the Create Form or Create Form and Report wizard for those columns.

Figure 8-6. APEX Attribute Dictionary, using the Update Using Items interface

Alternatively, from the Attribute Dictionary dashboard, you could opt to update the items on your page with attributes in the Attribute Dictionary. To do so, select the option in the Update Page region, and then select the items to update on your page. Applied in either direction, this ability to synchronize item attributes is a huge timesaver that adds quality and consistency to your application.

End-User Documentation

User documentation for an APEX project may take many forms, but the least costly, most valuable documentation is often contained in user help text. User documentation in the form of help text should take the same format on every page. Individual item help, tooltips, or page help are all acceptable, as long as the mode of help is consistent across your application, and perhaps across an entire suite of applications. Users don’t like change, and they don’t like unexpected surprises. If all your interfaces operate on the same general flow and look-and-feel, user confidence is higher and user feedback is improved. We have just forwarded our working software while providing simple documentation at least cost. A win-win situation!

Remember the standard APEX help items must be updated by a developer. Changes to help text necessitate an application change—and a round through the promotion cycle from development to quality assurance to production. This is good if source control and change management are tied in with your promotion cycle. This can be costly if promotions are performed manually, and if there is a system of approvals and system change request tickets to go through.

If you need to make help changes independent of application changes—perhaps users are requesting additional details, or your data is evolving such that additional instruction is required, or an entirely separate department of business users handles the help and documentation content—consider using your own table to hold help text, and building your own help regions and pages. All you need do is design and build your help table, build an interface for maintaining the help data, and assign the business users access to the maintenance interface, and you now have help text that can be dynamically updated through the Help Maintenance interface, by the business (or whoever is authorized to use the new interface).

If we developers have done our job right in building an intuitive, web-based application that uses a familiar look-and-feel, includes item-, region-, and page-level help text as outlined in our standards, and follows all other rules and guidelines for our project, the need for additional end-user documentation should be minimal.

When additional end-user documentation is required—and there will come a time—remember our theme of “just enough.” User tutorials may be necessary for more complicated forms or interfaces, or when specific formats or interfaces must be stipulated. When creating such documents, one suggestion is to make use of screenshots to create a pictorial step-by-step guide. A second suggestion is to build documents that can serve as both training manuals and reference documents, effectively cutting the documentation load in half. My opinion is that step-by-step tutorials are required only when the flow of the application is non-standard and non-intuitive. Your organization may mandate differently. In such cases, be sure to document and present the cost of building the documentation vs. the questionable value added. If you do need to document, do so only when the interface is finalized.

Developer Documentation

The point of developer documentation is to communicate to the next person (or yourself years later) how the application is built—the mechanical plumbing. Developer documentation for an APEX project includes the following:

• Following all naming standards
• Adding concise, meaningful comments in program code units: PL/SQL stored procedures, CSS files, JavaScript, and plug-ins, where applicable
• Religiously adding (and updating) developer comments
• Technical manuals only when absolutely necessary

Agile developer documentation begins with following guidelines and standards when building the application. Follow standards for naming conventions, page numbering, aliasing, region and item attributes, and the use of dynamic actions. Take advantage of plug-ins, where possible, for consistency of features, and to avoid duplication of code. All of these simple actions document your application because “this is how we do it.” The consistency afforded by standards makes an application easier to follow and easier to learn and maintain.

Write code comments where necessary to explain major steps or unusual algorithms that may not be readily understandable. Follow your organization’s standards for commenting (include dates, names, and ticket reference numbers). Comment with concise, accurate information as the code is developed. In APEX, where possible, use the developer comments. Developer comments are the entries in the Comments attribute of Page, Region, and Page Item elements. I am not saying to always add developer comments to every page, region, and item. That does not add value when the use of an item is obvious. I am recommending that you do add developer comments wherever necessary to explain a non-standard element or some special treatment, or to mark a change made for a bug fix. Those cases add value.

On occasions where a technical manual is either mandated or required due to some feature or complexity that needs more explanation than can be reasonably communicated in comments, write one. Be concise but thorough, and publish it in electronic format. My experience is that it is not necessary to document technical details of every item of every form and every report on every page (unless of course each of those items is used to interface with another system). It is necessary to document non-standard elements, non-standard feature usage or omissions, interesting security aspects, and anything that is not intuitively obvious to the next developer. Assume that your technical audience has both working knowledge of APEX and your subject matter, lest you end up in the task of writing an APEX manual (we already have a nice online one published by the APEX team) or a business document (which is better left to a subject matter expert). As a final note, do not write your technical documentation until your technical details are finalized, as late as possible.

System Documentation

Aside from the process documentation available through the APEX Utilities, system documentation should most notably include source control and change management. A good source control system—any source control system—serves as documentation of the evolution of your code base. The most important two words about source control are: Use it.

APEX application files, because they are database packages, do not readily lend themselves to traditional checkout-checkin-build source control systems. However, application files are just files, and can certainly be tracked with any source control system capable of handling files (which had better be all of them!). It takes just a little discipline to export from APEX and import into your source control system, consistently. Granted, this export/import process will seem like a big effort, until it becomes a habit.

In recent projects, I have successfully used CVS and Subversion to track all DDL, DML, APEX application files and supporting documents of all types. In these cases, all scripts were submitted to QA, and upon approval to production for DBAs to execute and install. The use of source control was mainly manual, but due to the small team and privileged promotion process, it worked. While not airtight, it was cost-effective in that situation.

A better system is to completely automate the promotion process by developing promotion scripts that handle schema changes (DDL), file updates (CSS and JS), and application installation. For an excellent example of a system-wide promotion process that covers all aspects of an APEX project, see Chapter 9 of Expert Oracle Application Express. The chapter was written by Dietmar Aust. It describes best practices and procedures for requirements management, file system layout, automated DDL extraction, script-based promotion system, and Subversion integration for APEX projects. It is likely that one or more of the components of the configuration and life cycle management system that Dietmar describes may make sense for your environment. My point is not to prescribe that system for everyone, but to point out what is possible regarding system management and change history. Given what is possible, apply the principles of Agile documentation to discern the right solution for your project. Do just enough.

The key is to balance essential source control and change management requirements for your project with the costs to implement them at your site. At minimum, a control and promotion process should include manual or automatic logging of the components updated when, by whom, and why. The “why” should track back to a specific requirement, enhancement request, or comment, which could be tracked in the Team Development tool, or some other change control system. Here is another area where the use of Team Development is a low-cost method of tracking system changes—relatively low-cost, valuable documentation of your application development history.

The source control requirements of course are heavier if the costs of system failure are higher. In that case, a larger investment in source control and change management is justified. My experience is that source control and change management are usually undervalued, until there is a failure. Any process, manual, automated, or some combination, adds value in ensuring recovery of your system and documentation of its history. If the costs of failure are higher, a greater investment in system documentation, including change history and source control, is justified.

No matter what system you implement, its use should become another habit.

Documentation for Business Users

Business users may need documentation that confirms implementation of the business rules, validates defined use cases, or confirms conformity to industry standards. In each of the cases, the working software is the best evidence. Videos that demonstrate operation of your application may suffice. If the documentation must be formal text on a page, consider integrating charts, diagrams, spreadsheets, images, and snippets of APEX interactive reports as opposed to plain text. Each of these visual modes of communication conveys information more quickly and efficiently than typed words.

Business users can also take advantage of Team Development information through the Team Development interactive reports. This is another case where Team Development incurs no cost other than data entry time, and yields valuable forms of documentation. This again promotes the core principles of simplicity and collaboration between the business and developers.

Business rules often need to be referenced or included as requirements in end-user or supporting documentation. When possible, strive to write the rules once, preferably into an online form, and generate reports from the stored data that communicate the desired business rule information. If business rules or use cases have been added as Team Development features, simple interactive reports on that data allow business users to pull the information they need when they need it. Business rules are apt to change over time, so there is value-added in creating a maintenance interface that also serves as an interactive report of your business rules repository. There is significantly less value and greater cost incurred in creating a Word document that must be maintained each time there is a business rule change, besides the fact that it pulls a developer away from writing code.

Trainers

If you have followed the principles of standard, Agile APEX development and produced simple, intuitive HTML pages, your training materials may be as simple as scripted how-to tutorials. Write one tutorial that covers the basic features of your application. Write additional tutorials for how to use more complicated, non-intuitive features. Gauge your writing to your audience. Non-technical users who are using their first online application will need more detailed instructions than a seasoned team of data entry users.

Test-drive your training materials as you develop them by working collaboratively with members of your audience. Can they follow the steps easily? Are you missing steps? Your audience can tell you, and it is best they do so during the documentation process so you can adjust your level of detail when necessary. Use screenshots, many of them, to document the application flow. Screenshots communicate the message more efficiently than exhaustive, step-by-step text descriptions of every action on every page. More complicated pages will of course need more detailed descriptions in the form of more screenshots. Always use clear, succinct text in active sentences. My recommendation is to prepare training documents that double as online tutorials and reference material, or vice versa. The point is to not double-document—with a little planning, one document can serve several purposes.

Do you need printed training documents? This is debatable and depends on the trainer and the application. Trainers need an agenda to follow. Trainees like to have some tangible material that documents their learning experience. Is the printed page the best medium? Not in all cases. My suggestion is to deliver training documents that also serve as user reference guides in online format. If users desire to print them, they can.

Summary

Agile documentation is the application of Agile software development principles to documenting aspects of your system that are not communicated otherwise. The concepts are simple: do only what is necessary, in the most effective mode of communication possible, at the least cost to the project relative to the value added. Agile documentation is clear, concise, direct, and to the point.

APEX includes products and features that facilitate Agile documentation. The APEX Utilities and Team Development tools offer out-of-the-box, low-cost opportunities to document aspects of your project. Creating and following standards as a natural part of the development process serve to minimize the amount of additional documentation that is required. The User Interface Defaults, help text, and developer comment features allow a developer to incorporate Agile documentation during the development process. The online, simple intuitive nature of APEX pages (when designed and built accordingly!) means documentation in the form of screenshots, videos, and other online tutorial formats is often sufficient for training and reference purposes. When mandated corporate or regulatory documentation is required, build only what is essential, in the most expedient method possible.

Above all remember that the fact that we are producing documentation does not mean we are abandoning or ignoring the value of face-to-face communication. The only valid reason to create documentation is to supplement and add value when other forms of communication are not possible or are insufficient for the purpose. When it is necessary to invest in documentation, plan for and do as little as possible, as efficiently as possible, as late as possible, and deliver just enough for your audience.