Visual Basic 2005 Design and Development - Chapter 13 doc

Part III Development In this Part: Chapter 13 Documentation Chapter 14 Development Philosophy Chapter 15 Coding Standards Chapter 16 Bug Proofing Chapter 17 Testing Chapter 18 Deployment 18_053416 pt03.qxd 1/2/07 6:33 PM Page 359 18_053416 pt03.qxd 1/2/07 6:33 PM Page 360 Documentation Chapter 12, “Attributes and XML Comments,” explains how you can use attributes and XML com- ments to provide some automatic documentation for an application. That provides a nice starting point, but the result is hardly ready for customers to use. The XML comments are combined into an XML document that includes the XML comments surrounded by tags to indicate their purposes. You still need to do a lot of work to turn this into a user-friendly resource. There are also many kinds of documentation that don’t naturally fit in XML comments. Because they are in the code, XML comments tend to explain what the code does and how it works, rather than how the user can use the application. This chapter complements Chapter 12 by discussing kinds of documentation that you should pro- vide for an application. It explains in high-level terms the types of documentation that you should provide. It also explains how you can automatically turn the collected XML documentation into a more usable form. Documentation Timing Many developers leave documentation for the very end. They write and debug the application, often going past their original scheduled release date, and then slap together some documentation at the last minute. The result is usually poorly organized, badly written, and incomplete. It is also too late to allow enough time for training. If the application is complicated, users may need a week or more of training. If the number of users is large, or if all of the users can’t drop what they’re doing for training at the same time, you may need to run several training sessions at different times, so the whole process may take a month or more. The trainers leading the training sessions will probably also need several weeks to learn the system well enough to teach the users, and to develop training materials. 19_053416 ch13.qxd 1/2/07 6:34 PM Page 361 With this last-minute approach, even if you finish writing code on time, the users may not be able to actually use the application until a month or two later. Many developers and project managers are happy enough to meet their deadlines and send an application to the users, even if it doesn’t have documentation. In the short term, meeting deadlines is important, but if the result is an angry mob of unhappy customers, your reputation as a builder of high-quality software can be irreparably damaged. Even in the short term, you may not gain much by releasing a program without documentation if you are then flooded with technical support calls. A much better approach is to write documentation continually throughout application development. The initial project specification forms the start of the documentation. As system and other high-level designs are written, they are added to the body of documentation. Use cases, Unified Modeling Language (UML) diagrams, lower-level design, and other development documents are also added, so the amount of documentation grows as development progresses. Visual Studio lets you associate documentation with a programming project. Open the Project menu, select Add Existing Item, and select the documentation file that you want associated with the project. Now you can double-click the file in Project Explorer to open it. If the project is large, it will probably be broken into pieces so that developers can work on different pieces at the same time. Associating the appropriate documentation with each piece makes it easier for a developer to find the relevant files to read about the design or to update the documentation. You’ll still need to store higher-level documentation that deals with more than one piece of the application sepa- rately, but this technique works well for lower-level developer documentation. Many of these documents are used by developers to guide programming, so writing them not only lays the foundation for good user documentation later, but it can also have big payoffs during development. Good documentation gives the developers a common vision that they can use to guide development. It allows developers to make the same assumptions so that they can work on their pieces of code while staying in synch with other programmers. As the work continues, developers will find mistakes in the designs and correct them. That will mean that the documentation will also need to be updated. To preserve the project’s history, you should place the documentation in a revision control system such as Visual Source Safe (VSS) just as you do with code. When the documentation is modified, you should check the appropriate document out of the revision control system, update it, and check in your changes. If, for some reason, you don’t have a revision control system, you can save snapshots of the documentation each time you make a change. One way to do that is to email the revised documentation to yourself or to a special documentation account. This is less efficient than using a revision control system because those systems typically only save the differences between different versions of a file, rather than the entire new version, but disk space is relatively inexpensive these days. You may also want to use revision marks when you modify the documentation so that you can see what has changed from version to version. If you follow this approach, you may also want to accept all changes when you create a new version of a file so that you only see the changes since the previous ver- sion. It’s pretty hard to find a particular change if a document contains hundreds of changes made over a one-year period. 362 Part III: Development 19_053416 ch13.qxd 1/2/07 6:34 PM Page 362 If you use iterative prototyping or another development approach that requires frequent changes to the design, the project’s documentation will change a lot during development. Continually revising the doc- umentation can seem frustrating to developers who would rather be writing code. However, revising the documentation provides another opportunity for developers to mentally review the design. Often, refor- mulating the design in documentation can help developers discover unanticipated problems, and it can lead to a better design. Sometimes large projects have dedicated technical writers who specialize in writing user documentation and training materials. Writing documentation early and keeping it up-to-date can help technical writers immensely. This is particularly true for military projects, government projects, and projects in other organizations that have rigidly defined development processes. Frequent changes to the documentation can be even more frustrating to technical writers than it is to devel- opers, partly because the writers may not see the need for some changes. You may need to remind them that the changes are driven by customer requirements and design needs, and that they are not as arbitrary as they may seem. Translating changes in the developer documentation into changes in the user documents and training materials is much easier if you use a revision control system. Then you can compare revision dates to see which design documents have changed since the user documents and training material were revised. Revision control systems such as VSS can also display the changes to a document so that you can figure out what has changed in the documents and make the corresponding changes. Word processing applications such as Microsoft Word also have revision tracking capabilities. In Word, you can turn revision tracking on by selecting the Tools menu’s Track Changes command. Then you can easily see the document’s entire history and find changes quickly. Unfortunately, Word shows all changes, not just those since a specific date, so it can be hard to find the most recent changes in a document that changes frequently. If you save new copies of the document after each change, perhaps in your revision con- trol system, then you can use a difference tool to see what has changed between two versions. To compare to documents in Word, select the Tools menu’s Compare and Merge Documents command. In some development approaches such as staged delivery and some agile methods, development may never end. Instead, the program keeps evolving to adapt to new conditions and requirements. In those situations, the documentation must also evolve to match. The short cycle times often used by these approaches can make it hard to keep the documentation up-to- date. If an agile project releases a new version of the program every three to four weeks, the time needed to update the documentation can be a significant fraction of the total time for each release. Although keeping the documentation current is difficult in these sorts of frequent-release projects, it is particularly important. If the application’s features change monthly, the users must have reliable docu- mentation so that they can figure out how things should work on their current version of the program. It is also important that you label the documentation so it is obvious that it matches the current release. You should use the same numbering system for the documentation and the program. Program version 2.1.12 should come with documentation 2.1.12. The users should also be able to easily find the program and documentation version numbers so that they know they are working with the right documentation. It’s extremely frustrating to be doing exactly what the documentation says, but still get the wrong result because you have the wrong version of the documentation. 363 Chapter 13: Documentation 19_053416 ch13.qxd 1/2/07 6:34 PM Page 363 If users may be working with different versions of the software, matching numbering systems will greatly simplify support. When a user calls with a question, the support engineer can ask for the program’s ver- sion number, and then use the corresponding documentation to find the problem. Documentation Types An application should include several different kinds of documentation. You can group them according to their target audience: users and developers. User Documentation User documentation is intended for use by the application’s eventual users. This includes those who will actually use the program on a regular basis, and those who are involved in specifying and designing the application. It includes the executives who approve and monitor the project, and the “power users” who help determine its functionality. It also includes trainers who will teach the users and support engineers who will answer the users’ questions when they use the program. The following sections describe some of the types of user documentation that a typical project might need. What the project actually needs varies, depending on such factors as how large the application is, the number of users, and how formal the development effort is. For example, I’ve worked on simple projects designed for two or three users where the user manual was good enough for training. I’ve also worked on projects designed for use with several hundred users where trainers developed a full-blown curriculum. Overview The overview document provides a high-level description of the program’s purpose and operation. An executive summary describes the program as succinctly as possible. More detailed sections describe the application’s environment, other systems that it interacts with, who the users are, and so forth. This document should focus on high-level ideas, rather than the program’s specific implementation and usage. Typically, this is a relatively short document of one to ten pages. Sometimes the overview is included in the specification, but it’s also useful to be able to pull it out to give to executive-level readers who don’t need all of the detail provided by the specification. Specification The specification provides a detailed description of exactly what the program should do. It focuses on how the program helps the users perform their tasks without explaining how the program works. This document is updated throughout application development, so it is often called a “living specification.” Specifications are often extremely detailed and can be very long. If you use iterative or agile techniques, the specification usually grows over time, so it can be quite long by the time the application is finished. I’ve worked on projects with specifications ranging from one or two pages to several hundred pages. 364 Part III: Development 19_053416 ch13.qxd 1/2/07 6:34 PM Page 364 Use Cases These are scenarios that describe how the program lets a user perform a specific task. They describe the task, expected inputs and results, and the exact steps that the user needs to perform to accomplish the task. Often, use cases are included in the specification and help define the application’s requirements. It is also useful to be able to pull them out so that users, developers, and testers can test the growing applica- tion to see whether it handles the use cases. User Manual The user manual describes every part of the application from the user’s point of view. It may include tutorials that introduce new users to the application and tutorials (or “How-To’s”) that explain how to perform specific tasks, possibly those described by the use cases. The user manual should use an instructional approach, much as a textbook does, so that the user can read the chapters in order to learn about different parts of the system. The user should not need to jump around to read about specific topics. After reading the manual, a typical user should be able to use the program reasonably competently. The manual may also include sections describing advanced concepts and techniques. Usually, the user manual should not include the full detail provided by the specification. The specifica- tion is designed to let developers and customers decide whether the application does what it should. The user manual is designed to help end users learn how to perform their day-to-day tasks. Help Files The help files explain parts of the system to the users while they are running the application. The help should describe each form and dialog in the application. Ideally, the forms and dialogs should provide a way for the user to open the corresponding help page. The help for a form or dialog should explain the purpose of every control that it contains. Obvious con- trols such as a First Name text box only take a short sentence to describe. Though it may seem excessive to document every name, address, and phone number field, it’s easy to write descriptions of these, and it’s easy for the users to skip them if those fields don’t confuse them. A simple statement such as “The cus- tomer’s billing address street number” can also be quite helpful when the user can’t figure out whether an address is for billing, shipping, the customer contact, or something else. Controls that are more complicated or confusing need longer descriptions. A good description of a com- plex topic can save you technical support calls. Don’t be afraid of describing seemingly obvious facts in some detail. Users only look at the help when they are confused and they don’t find the form obvious. Users are rarely offended by help that is too descriptive. They are much more irritated by incomplete help. An annotated screen shot of a form or dialog can tie controls to their descriptions concisely. Often, the user manual is included in the help system so that the user can easily review its material and search for tutorials that show how to perform specific tasks. It may still be useful to provide a separate printed version of the user manual, however, so users can read it away from their computers. 365 Chapter 13: Documentation 19_053416 ch13.qxd 1/2/07 6:34 PM Page 365 Context-Sensitive Help Context-sensitive help provides help based on the controls with which the user is interacting. For example, if the focus is in a street address field, the user might press F1 to view the help for that field either in a help file or in a popup window. This information is probably duplicated in the main help file describing the form containing the field. In Visual Basic, you can display a help button in the form’s title bar. When the user clicks this button, the cursor changes to an arrow with a question mark. If the user then clicks a control, Visual Basic raises the control’s HelpRequested event and the program can display appropriate help for the control. A control’s HelpRequested event is also raised if the user presses F1 while focus is in that control. Figure 13-1 shows the HelpButton example application. You can see the question mark arrow cursor hovering over the First Name text box. Figure 13-1: When you click the help button in the title bar, the cursor changes to a question mark arrow. The following code shows how this example works. This example stores a control’s help string in its Tag property. When the form loads, the program sets a HelpRequested event handler for each of the form’s controls. The HelpRequested event handler simply displays the control’s Tag property. Public Class Form1 ‘ Add a HelpRequested event handler to every control. Private Sub Form1_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load For Each ctl As Control In Me.Controls AddHandler ctl.HelpRequested, AddressOf Control_HelpRequested Next ctl End Sub ‘ Display help for the clicked control. Private Sub Control_HelpRequested(ByVal sender As Object, _ ByVal hlpevent As System.Windows.Forms.HelpEventArgs) ‘ Get the control. Dim ctl As Control = DirectCast(sender, Control) ‘ Display the control’s Tag property. Dim txt As String = DirectCast(ctl.Tag, String) If (txt Is Nothing) OrElse (txt.Length = 0) Then MessageBox.Show( _ 366 Part III: Development 19_053416 ch13.qxd 1/2/07 6:34 PM Page 366 “Sorry, there’s no help for control “ & ctl.Name, _ “Help”, MessageBoxButtons.OK, MessageBoxIcon.Information) Else MessageBox.Show( _ txt, _ “Help”, MessageBoxButtons.OK, MessageBoxIcon.Information) End If End Sub End Class Example program ResourceContextHelp (available for download at www.vb-helper.com/ one_on_one.htm ) shows another approach that stores help strings in the project’s resources. When the user clicks the help button and then clicks one of the controls, the event handler builds the name of the resources that should contain the control’s help string. It uses My.Resources.ResourceManager to get the resource string and displays it if it exists. Unfortunately, Visual Basic ignores the form’s HelpButton property if either the MinimizeBox or MaximizeBox property is True. That means you can only display the help button on forms that can- not be minimized or maximized. In many applications, that basically means the dialogs. Pressing F1 while a control has the focus still raises its HelpRequested event even if the help button is hidden, so you can still provide this kind of help on forms that have Minimize or Maximize buttons. The HelpProvider component provides another way to display context-sensitive help. Figure 13-2 shows the HelpProvider example program using as HelpProvider component. In this figure, I clicked the help button and then clicked the State text box. The HelpProvider component displays the help in a popup. Figure 13-2: The HelpProvider component displays help in a popup. To use a HelpProvider, add a HelpProvider component to the form. To display a simple string for a control, set the control’s HelpString property that is added by the component. For example, if you give the HelpProvider the name hlpFields, each control on the form gets a new property called HelpString on hlpFields. If you set this string, the HelpProvider automatically displays it when the user requests help. For other features provided by the HelpProvider component, see the online help. 367 Chapter 13: Documentation 19_053416 ch13.qxd 1/2/07 6:34 PM Page 367 Tooltips Tooltips provide a tiny amount of additional documentation for the user. They are unobtrusive, so experi- enced users can ignore them easily. If you forget what a field is for, you can hover the mouse over the field to see the tooltip. To give a control a tooltip, add a ToolTip component to the form and then set the control’s ToolTip prop- erty added by the component. For example, if you give the ToolTip component the name tipFields, every control on the form gets a new property named ToolTip on tipFields. After you set the controls’ ToolTip properties, the ToolTip component displays the tooltips automati- cally. Figure 13-3 shows example program TooltipHelp displaying a tooltip for the City text box. Figure 13-3: The ToolTip component displays tooltips for controls. Users who have vision impairments rely heavily on tooltips. The screen readers used by these users depend on tooltips to help the user understand the application better. Training Materials The type and amount of training materials needed for a project vary widely, depending on the complexity of the project and the number and types of users. A simple project designed for use by one or two users won’t need much in the way of training materials. The user manual and an hour’s time with the project manager may be enough. For a complicated project intended for use by many users, training may involve a week or more of detailed instruction and hands-on study with handouts, slide shows, demon- strations, catering, and hotel rooms. Often, the training materials will cover much of the same material included in the user manual. It should include an overview, basic instructions for using the application, and some specific examples. It may include hands-on exercises that let the users experiment with the application on their own with the instructor present to lend a helping hand. You can make that sort of hands-on training easier if you plan for it from the beginning. In particular, you should try to design the application so that it can easily work with test data that students can destroy with- out affecting real operations. Training users on live production systems can be difficult and dangerous. While the training materials may be based largely on the user manual, much of the material may need to be rewritten to work in a classroom setting. 368 Part III: Development 19_053416 ch13.qxd 1/2/07 6:34 PM Page 368 [...]... load the XML document into a Visual Basic application and process it The XmlDoc ToText example program, available at www.vb-helper.com/one_on_one.htm and described in the following section, does that It uses the XML documentation to produce a textual representation of the code Program XmlDocToText Program XmlDocToText reads an XML document file and produces the display shown in Figure 1 3-5 This figure... methods, and events The other links at the top lead to sections on this page 381 19_053416 ch13.qxd 1/2/07 6:34 PM Page 382 Part III: Development Figure 1 3-6 : Program XmlDocToHtml builds this index page from an XML document Figure 1 3-7 : Program XmlDocToHtml builds this detail page for the Person class Figure 1 3-8 shows the bottom half of this page The XmlDocToHtml program uses the structure of the DocNode... files NDoc uses reflection to gather extra information about the code that is not included in the XML documentation For example, it discovers the inheritance hierarchy of the classes it is documenting and adds that information to its output Figure 1 3-4 shows an NDoc help page for one of the Person class’s two constructors Figure 1 3-4 : NDoc uses reflection and XML documentation to build Web and help... fixed, or the specification revised High-Level Design High-level design documentation describes how the major pieces of the application fit together It includes architectural and platform decisions, and describes the application’s biggest systems System-Level Documentation Whereas high-level design explains how the application’s major systems fit together, system-level design explains how the systems work... defines values Developer, ProjectManager, and VicePresident The class has two private fields (variables) called m_EmployeeClass and m_Office, and two public properties called EmployeeClass and Office Figure 1 3-5 : Program XmlDocToText displays a project’s code hierarchy 376 19_053416 ch13.qxd 1/2/07 6:34 PM Page 377 Chapter 13: Documentation You can examine Figure 1 3-5 to learn more about the code hierarchy... - Global Types ‘ - - Global Enums and Constants ‘ 370 19_053416 ch13.qxd 1/2/07 6:34 PM Page 371 Chapter 13: Documentation ‘ - Global Variables ‘ - ‘ ‘ ‘ ‘ ************************************************ Private Definitions -Private API Declarations ‘ - Private Types ‘ - ... help, context-sensitive help, tooltips, and training materials Developer documentation includes the project specification, high- and low-level designs, and inline comments Comments within modules provide a good place to store module-level documentation, because the documentation is guaranteed to remain with the module Use standard comment templates to ensure that all developers follow the same documentation... param element, and adds the result to the HTML table’s second column Figure 1 3-9 shows the resulting table Figure 1 3-9 : DocNode function Parameters builds an HTML table built from param tags 386 19_053416 ch13.qxd 1/2/07 6:34 PM Page 387 Chapter 13: Documentation Function ProcessXml shown in the following code converts a piece of the XML document into HTML code It replaces see, seealso, list, and other... 19_053416 ch13.qxd 1/2/07 6:34 PM Page 383 Chapter 13: Documentation contained in History XML comments The See Also section contains links defined by seealso tags in the XML comments The page ends with a link back to the hierarchy index shown in Figure 1 3-6 Figure 1 3-8 : The bottom of the Person class’s Web page displays ancestor and history data Program XmlDocToHtml is much longer than program XmlDocToText,... node’s name element and uses it to create a new DocNode object It passes the DocNode constructor the XML node representing the assembly, the assembly’s name, and the character A to indicate that this is an assembly node The code uses this DocNode as the root of a tree of DocNode objects 378 19_053416 ch13.qxd 1/2/07 6:34 PM Page 379 Chapter 13: Documentation Next, the code gets the document’s members . Part III Development In this Part: Chapter 13 Documentation Chapter 14 Development Philosophy Chapter 15 Coding Standards Chapter 16 Bug Proofing Chapter 17 Testing Chapter 18 Deployment 18_053416. classes it is documenting and adds that information to its output. Figure 1 3-4 shows an NDoc help page for one of the Person class’s two constructors. Figure 1 3-4 : NDoc uses reflection and XML documentation. Visual Basic code and practically no com- ments. The application was several years old and pieces of it had been written, rewritten, and rewritten again in everything from Visual Basic 3 to Visual