Why use software development management techniques ?

During the past few years, many articles and books have been written about managing software development projects. Software development projects using TEX require some special attention. This presentation looks at the entire software development life cycle as it applies to TEX and the following issues in particular: requirements specification, design specification, coding standards, code review checklist. Requirements specification The first step in any software development project should be to create a document known as a requirements specification. This document defines the project in very broad terms. A copy of the requirements specification should be given to everyone involved in the project; any time a requirement changes, everyone involved should be informed of the change by receiving an updated requirements specification document. The requirements specification should include: Description. I am amazed at how difficult it is to describe some projects. If it is not possible to write down a simple paragraph that gives a valid description of the project, that project is not well defined and has a high probability of getting out of control. Project goal. Once the project is described a goal or goals can be defined: “If you don’t know where you are going, then how can you know when you get there? ” Defining the project goal can force important issues to surface at the start of the project. A written project goal provides a means to objectively measure the success or failure of a project. Needless to say, the project goal should be documented and understood by all members of the software development team as well as the project manager. Failure to have a documented goal will lead to feature creep and project drift. Overview of problems to be solved. Describe the fundamental problems that need to be solved. Converting the existing data into a usable format may be a real challenge. Word processing files, poorly organized databases with little or no documentation, and spreadsheets can, and often are, the only available format for the data. All must be converted into a format suitable for typesetting with TEX. Tasks/Functions. Specify the tasks or functions the macros perform. For example, if there are any extracted indexes or page cross references they should be defined. Current mode of operation. It is useful to know the current mode of operation. This avoids the problem of creating a solution that cannot be easily integrated into the working environment of the user. For example, if the user is a hard-core plain TEX user, providing a set of macros that only work under LATEX would not be an appropriate solution. Communications. Does the user expect the data back in some other format? One rather large project that I was involved in required converting data from a proprietary typesetting format into SGML, typesetting a book, and producing an electronic version of the data on CD. We finished the book and the CD and figured we were done for the quarter when the client called up and asked us about the “mag-tape version”? Our marketing department had forgotten to tell us that we had to create yet another deliverable. The data was to be delivered on an IBM formatted 6250 BPI magtape with a specific tape label. The requirements document should have specified that deliverable. Unfortunately it did not, and we had to scramble to pull together the resources to complete the project. If the data undergoes any conversion processes it is important to specify the life cycle of the data and its changes. This means that the date (and possibly the time) when the data is frozen for production should be specified. If the data is modifed for typographic reasons during the production process, it must be specified if the original data is to be updated to match the typographic changes. For example, if the data is in SGML or XML it is common to add processing instructions to the data to help with the typography. It is sometimes necessary to make structural changes in tables, particularly CALS SGML tables, to make 1 Continuous Acquisition and Life-Cycle Support (formerly Computer-aided Acquisition and Logistics Support) (CALS) is a Department of Defense (DoD) strategy for achieving effective creation, exchange, and use of digital data for weapon systems and equipment. MIL-PRF-28001C is the military stanTUGboat, Volume 20 (1999), No. 3— Proceedings of the 1999 Annual Meeting 299 Managing TEX Software Development Projects them typeset properly. Changes of this type require complex changes to the source. If the data must be returned in a format that could be used again, the returned data must include the structural changes to the table elements. Another example involves the creation of a printed book and an electronic product, e.g. CDROM. Typographic changes due to typesetting the book may need to be reflected in the CD. Failure to document this requirement can lead to serious problems if the products get out of sync with each other. Ease of use. Specify how experienced with TEX the user of the macros should be. It is all too easy to create macros that only an expert can use. Occasionally, however, it is appropriate to create complex macros. The key is to document the expertise needed, since the level of experience of the user also defines the amount of detail that the documentation needs. Hardware/Software. Specify the hardware platform(s), operating system(s), and implementation(s) of TEX that the macros will run on. This is important if you are using some of the modified implementations of TEX like ε-TEX, Omega, or PDFTEX. Some implementations of TEX are compiled for a particular memory size. Other implementations are configurable. In either case, the minimum and recommended TEX memory size should be specified. This will let the user know if they have to use a larger version of TEX or reconfigure their existing version. TEX has a very small memory footprint by today’s standards. Unfortunately some of our users have just about everything running on the PC at one time. One of our users has the following programs running at all times: Excel, Word, Outlook, Internet Explorer, and several other proprietary pieces of software. “Bloatware” software packages can use up tremendous amounts of local disk space and memory. Attempt to define the possible interactions that might occur if other software packages are running. Define the amount of both network and local hard disk space required. dard for CALS markup requirements. A soft copy of this is available at: http://www-cals.itsi. disa.mil/core/ standards/28001C.pdf Because CALS tables are designed to support the entire DoD they are very complex and difficult to use. Quality. Outline in broad terms the rules for word, paragraph, column, and page breaking. Performance. TEX is a high-performance typesetting system. Usually there is no need to worry about performance. However, the generation of PDF pages on demand by a web server can become a performance issue. List all performance criteria. Compatibility and migration. Specify if the macros are based on plain or LATEX or something else. Specify if the macros have to be compatible with any other macro package. If the macros are a replacement/upgrade of an existing package specify what amount of re-learning will be required of users as they migrate their data to the new package. International. Specify the need to support running and/or continued heads that may include support for R © and TM as well as accented characters. Specify how R © and TM are to be typeset: superscript or not, serif or sans-serif or font dependent. Itemize the languages to be supported. Each language requires it own hyphenation dictionary. The encoding of the input data should be defined. Determine if the data uses the Latin-1 encoding or some other format, e.g. UTF-8. There is a lot of data with accented characters that uses MS-DOS code page 437 or 850. This data is not compatible with the TEX standard encoding or 8r, used with most PostScript fonts. The way the data is encoded should be documented. Service and support. Itemize the level of service and support. The days and hours when support is available should be listed in detail. Pricing/Licensing. Define the ownership of the macros. Specify the method by which the source code will be provided and if the source code can be de-commented. Design specification Creating the design specification document can be done in parallel with creation of the requirements specification document, but it should not precede it. It is important to understand what is required prior to defining the design of the pages. 2 The term “code page” refers to the keyboard and display encoding. When MS-DOS was developed there were no accepted standards for the layout of accented characters. Code page 437 was the default layout for the version of MS-DOS that what shipped to the United States, and code page 850 was the default layout for Wester Europe. 300 TUGboat, Volume 20 (1999), No. 3— Proceedings of the 1999 Annual Meeting Jeffrey McArthur Publishers often provide design specifications, but publisher-supplied design specifications are often incomplete, vague, and ambiguous. Even when the publisher provides such information, a document should be created that defines all the details required by the project. Documenting the specifications also gives the typesetter a mechanism to generate additional revenue when the publisher makes changes at the last minute. Description. Give a detailed description of the typeset pages. Output format. Define the output medium. Resin-coated paper and film are still used as well as electronic formats. The design specification document should unambiguously define the format of electronic files. There are many possible standard electronic formats: PostScript, PDF, or separate EPS files. If the deliverable is in PostScript, identify which PostScript level 1, 2 or 3 is required, and if the files are to be DSC-compliant (Document St