SSD9: Software Specification, Testing, and

Maintenance
 Unit 7. Documenting the Solution
 7.1 The Documentation Life Cycle
 7.2 Documentation during Implementation
 7.3 Final Documentation
 7.4 Why Document?
 7.5 Documentation Aids

 Assessments
 Exercise 8
 Multiple-Choice Quiz 7
 Software = program + documentation
 The software development process is
 not only the production of code in machine-readable format
其实 code 可看作一种特殊形式文档
 but also the production of all the documentation — an
intrinsic component of every project.
 Software includes all kinds of documents produced
at different phases of the software life cycle:
 specifications
 design documents
 planning documents,
 legal and accounting documents,
 management documents, and
 all sorts of manuals. ( 安装使用手册、开发手册 )
 importance of documentation
 We have emphasized
 the importance of documentation throughout this course.
 the different types of documentation produced during the
software development process
 we will study
 the criticality of good documentation as an intrinsic part of
the software process. 固有的过程
 Note
 Note
 There is no specific chapter or section of your textbook
devoted to documentation, although references to the
importance of documentation are found throughout.
 in this unit, there will be little additional reading.
 7.1 The Documentation Life Cycle
 Recall the life-cycle models. Notice that
 there is no separate documentation phase in Software Life
Cycle
 Documentation is an ongoing activity throughout
the software process. 自始至 终贯穿整 个过程！
 the documents associated with each life-cycle phase.
Life-Cycle Phase Document Types
Requirements Analysis Requirements document or rapid prototype
Specification Specification document
Design Architectural design / Detailed design
Implementation Inline and module documentation
Module testing document, test suites, test
results
Integration Integration testing document, test suites, test
results / Final documentation for delivery
Maintenance Updated requirements, specification, design,
testing documents
Updated module documentation
Retirement No documents created
 pre-implementation phases,the documents are the products
of that phase.
 requirements analysis phase,
 there may be an actual text document, or
 requirements may have been elicited via rapid prototyping.
the final prototype is the requirements document
 specifications phase ， include all the different types
of specification artifacts.
 informal specifications,
 data flow diagrams,
 control flow diagrams and
 decision trees,
 the data dictionary,
 input-output specifications, and
 entity-relationship models.
 pre-implementation phases,the documents are the products
of that phase.
 design phase, documents include
 the formal architectural and detailed design documents.
 more informal documents, 还有其他各种形式的文档
 records of discussions over specific design issues.
 the module and integration testing documents
 including
 instructions for testing
 test suites (although they will be different in the two phases).
 the results of testing
 the number and type of faults found.
 Build and Test the Solution, these test statistics will
help the developer
 estimate the quality of individual modules and the product as
a whole
 be on the lookout for errors in subsequent tests of the same
product and future products
 estimate the necessary amount of testing time remaining.
 the maintenance documents
 no new documents are produced from scratch, but
documents from practically every phase of the life
cycle will be subject to revision. 主要是 修改及增 加
原有文 档的内容
 7.2 Documentation during Implementation
 Who are responsible for documenting the code?
 Programmers.
 Code documentation includes
 both inline comments
 and more top-level documentation describing the code in a
module or class in general.
 Who are expected to read the code line by line?
 maintenance programmers having to fix a specific fault
 SQA group members doing a code inspection.
 In most software products, the code is divided into
 modules containing one or more functions, procedures, or
classes
 variables that store state for the module.
 The module prologue ( 模块说明 ) is
 the set of comments at the top of the module
 that describes the purpose and contents of the module in
general.
 list of the information that should appear in the
module prologue:
 Including
 The module name
 A description of what the module does
 The programmer’s name (or names, if more than one
individual is responsible for the module)
 The date the module was coded
 The date the module was approved and by whom
 The module arguments (If more than one function,
procedure, or class is contained in a single module, the
prologue should give the arguments and a brief description of
functionality for each item.)
 list of the information that should appear in the module
prologue 模块说明
 Also including
 A list of variable names in alphabetical order and how they
are used
 Names of files accessed by the module, if any
 Names of files changed by the module, if any
 Module input/output, if any
 Error-handling capabilities
 The name of the file(s) containing test data (to be used for
regression testing)
 A list of modifications made, by whom, on what date, and
approved by whom
 Known faults of the module
 Use a standard module prologue template
 It is easy to provide a standard module prologue
template that a programmer can copy and fill in for
a new module. 做一 个 模板
 There are also CASE tools that can
 help in gathering documentation contained in the code and
 make it available in a public location for client modules.
 Javadoc, the Java API documentation generator Detailed
Design Specification.
 7.3 Final Documentation
 Maintainer's Documentation
 Installer/Administrator Documentation
 User Training Materials
 User Reference Manual
 User Quick Reference
 Maintainer’s Documentation
 Maintenance of custom software is likely to be done
by the developer’s organization
 but in some cases, the client will take over maintenance 有时
用户自行维护
 either right away or later during the maintenance phase.
 Maintainer’s documentation may include
 specifications
 design documents
 testing documents
 general documentation about the modules of the product and
their interaction.
 Installer/Administrator Documentation
 The client will need to know
 how to install
 generally administer the software product.
 These documents include instructions on:
 Installation of the software on one or more platforms, if
applicable
 Initialization procedures, if required 如下拉列表项
 Integration of updates and patches during maintenance
 Any other activities related to the software product that
would be performed by the systems division of the
organization rather than the end users 如客服
 User Training Materials
 Training materials guide first-time and novice end
users through the functionality of a system in a
simple way.
 approachs to developing training materials
 present different scenarios of use, and lead the user through
each one, using a realistic example throughout the scenario.
和某些 photoshop 图像处理软件教程 / 网页动效类似，各
种效果案例
 give examples of uses and then present example problems
(with solutions) for the user to practice.
 User Training Materials
 User Training Materials
 should cover all the major functionalities of the system,
 but they do not necessarily have to cover every single aspect
of the system. 过于简单则没有必要写入
 E.g.,
 contain pointers to the user’s reference manual for more
complex or less common operations
 provide training for these operations in staged scenarios
ordered by complexity. 操作的难易级别分级
 User Reference Manual
 A user reference manual contains a complete
description of the functionality available in the
product.
 Reference manuals contain
 lists of available APIs or
 interface operations,
 organized
 by topic or 各类应用主题（如按照各业务项目分类）
 by the major functions performed by the system.

 The user reference manual should

 explain all relevant terminology and 可组织一个术语表
 provide complete descriptions of all aspects of the system.
 User Quick Reference
 A user quick reference is a brief document or card
that shows at a glance the functionality available in
the system and how to access it.
 If small systems, the quick reference may be able to include
brief descriptions of all the functionalities (commands) and
expected arguments.
 In larger systems, it is probably only feasible to provide a list
of the most common operations organized by topic — and a
reference or link to more detailed information in the user
reference manual.
 7.4 Why Document?
 The attitudes of organizations toward
documentation can vary widely. 不同组织 对文档
的 z 重视程 度 不同， 要求也不同
 Some organizations consider the product can be
understood simply by reading the source code. self-
documenting 其实很 难做好！
 Unfortunately self-documenting code is rare indeed.
 Organizations that devote the proper amount of
attention to documentation will find that investment
in this effort pays off. 专门投 入人力物力 做文档
工作 , 并从中 得到回报 ！磨刀不 误砍柴功！
 devote the proper amount of attention to documentation
 Other organizations are far more documentation intensive.
 create specifications and detailed design documents for the
implementers.
 The testing process is carefully planned and its results logged.
 Requests for changes during the maintenance period have to be
submitted in writing, justified, and formally approved. 书面报告需求
变更、需要评估及通过
 Once authorized, modifications are not incorporated into the product
until the documentation has been updated and the changes approved. 文
档修改好了并通过评审，才能做代码修改
 In the waterfall model, it is stipulated that no phase is complete
until the documentation and other artifacts of that phase have
been completed and approved by the SQA. 回想 一下 ，瀑 布
模型就是规定这样做的！
 Important reasons
 Even in other life-cycle models, it is important for several
reasons that each phase be fully documented for the current
version of the product before the next phase begins.
 1, if the documentation is postponed, the pressure to deliver a product on
time may be such that the documentation is never completed. 时间少，任
务紧！一旦拖延可能就没有机会完成文档工作了，
 2, the individuals who were responsible for earlier phases of the project
may no longer be working on that project or even for the same
organization.
 Due to the very high rate of personnel turnover in the software industry,it
is almost certain that the programmers who will be maintaining the product
are not the same individuals who developed it. 人员更迭频繁！
 3, a design will often be altered during implementation, and unless the
design has been fully documented by the team, it will be difficult to carry
out the modifications and to document the design after the changes. 改好
代码后再去动文档，几乎很难做到 , 做好！
 4, poor documentation, no documentation at all, or, even worse, incorrect
documentation is a nightmare for maintenance. 维护时碰到糟糕甚至是错
 a thorough documentation process
 So, the management of the developer’s organization should
plan — from the beginning of the entire software project —
for a thorough documentation process. 为文档工作安排计
划
 Documentation should be updated continually to reflect the
current version of the product.
 Documents pertaining to each life-cycle phase should be
completed by the same people who participated in that
phase. 各负其责，自行完成本阶段文档
 Finally, before delivery to the client, the documentation
must undergo a final check to make sure that
 it is complete and 完整性
 consistent with the code. 一致性
 For the client
 the developer should remind the client that
allocating proper resources to documentation is a
priority for both sides. 双方都 要重视文 档 工作
 A badly documented product will require more money and
more time to maintain.
 Poor documentation may also end up being a motivation for
replacing the product rather than maintaining and enhancing
it — a course of action that can be very disruptive to the
client’s organization. 看着糟糕的文档都不想维护、改进了
，直接重做！
 7.5 Documentation Aids
 Producing documentation can be a significant activities
during software development.
 Studies shown that an organization may produce
 for an internal product from 28 to 66 pages of documentation per 1000
instructions (KDSI)
 For commercial product from 28 to 66 pages of documentation around
50 KDSI.
 For operating system software, the number may go as high as 157 pages
of documentation per 1000 KDSI.
 These studies considered various sorts of documents,
 planning, control,financial, and technical documents
 comments in the code.
 文档编写的工作量很大
 a survey showed that for
 every 100 hours spent on activities related to code,
 150 - 200 hours spent on activities related to documentation.
 documentation can consume so much of an organization’s
resources
 it is vital to make the process of developing and maintaining
documentation as efficient as possible.
 CASE tools can help with organizing and keeping up to date
of all kinds of documentation, such as plans, contracts,
specifications, designs, source code, and management
information.
 Not only reduce the burden associated with these tasks
 also help in making documentation available online.  easier to search
and to change.
 维护文档一致性的好办法
 Furthermore, it is significantly more cost-effective to
 make document modifications in one location and make the most recent
version available online to all interested parties
 than it is to keep redistributing corrected paper copies 尽量不要用纸质
拷贝分发
 documentation standards
 documentation standards aid to effective document
production. 遵循标准，提高效率
 Uniform coding standards assist maintenance programmers in
understanding source code.
 Standardization is even more important for user manuals,
 read by a variety of users, few of whom are computer experts.
 Uniformity in documentation also
 reduces misunderstandings between team members
 aids the SQA group in performing their job.
 开发团队文档编写标准一致，转部门转项目开发就轻
松许多
 documentation standards are consistently applied throughout an
organization
 new employees will need to be trained in applying the standards when
first joining an organization
 they will not need retraining when they change departments within the
organization.
 Where standards already exist, they should be adopted
 Standards for all the documentation that is to be produced
during software development must be established during the
planning process and incorporated into the software project
management plan (SPMP). （课本 9.5 小节）
 Where standards already exist, they should be adopted
 the IEEE Standard for Software Test Documentation [ANSI/IEEE 829,
1983]
 the IEEE Standard 1063 for Software User Documentation
 Existing standards should appear in section 1.4 of the SPMP (Reference
Materials)
 effort-specific standards in section 4.1 (Methods, Tools, and
Techniques).
 the framework for a SPMP
 the framework
for a SPMP （ ch4 ）