A. Version History
|
Date |
Revision |
Descriptions
|
Author |
|
2017-02-14 |
A |
Documents created and finalized |
Vinh Nguyen canvin@gmail.com |
In
order to get ISO or CMM certification, software development organizations have to
provide traceability of defects to its requirement sources as well as
implementation codes covered the whole requirements.
Water
Fall methodology is a rigid process, where documentation is very important.
Each phase must provide required documents to the subsequent phases before the
next phase started. This is also good as future enhancement would be easier to
base on technical documents rather than reading source codes. New staff could
learn the system quicker by reading technical documents.
Agile
methodology is like an ad-hoc methodology, where developers discussed issues
and development strategies in meeting called scrums. This methodology is
applicable for a small software system. Without proper technical documents,
enhancement or additional features would require expertise of existing staff to
read source codes. If the system is large enough, reading source codes would be
very difficult, which would slower development time, and leaving room for bugs.
It would also be hard to optimize system performance. Learning curve would be
longer for new staff.
In
both methodologies, project managers have come up with time and task plan, with
inputs from senior or team leaders for a project. Usually project managers
wanted meetings with teams to get updates to make sure that development were on
track, i.e. time consuming to developers to estimate work done or remaining
work.
We
should pick good strategies from each methodology to make our development cycle
shorter, but it also provides quick implementation of new features.
2.
Software Development
Process
Figure 1. Software System
Development Process
The
above development process describes the implementation of new features on an
existing system, where technical documents must be created or updated to
reflect requirements by a customer. For example,
-
Requirement
Specification drafted by a customer and a Business Analyst. This is a project document, which would be
obsolete after the implementation of new features completed and delivered.
Because of limited knowledge of the system, this requirement specification was
at high level of understanding.
-
System
Implementation Proposal, a project document,
was drafted by a System Designer with clarification with the Business Analyst.
This would outline how the features would be like in the system, e.g. possible
look and feel, buttons, feature operations, etc. The proposal may be different
than customer had thought, thus the BA would discuss this with the customer
again to ensure that s/he would not be surprised when the system completed and
delivered.
-
After an agreement on the System Implementation Proposal, the System Designer would work with Subsystem Designers to design the
implementation of new features, which could be spread over many subsystems. At
this stage they would work out a protocol
specification, system diagrams, or database diagrams, which are product document to stay alive and
updated in each enhancement, to outline the interaction messages between
subsystems including exchanging parameters and their formats.
-
Based on the protocol specification, system diagrams, and database
diagrams, subsystem designers would work into details with components experts
in his team to come up with flow charts,
subsystem diagrams/protocol, and database schema, which are product documents.
-
All technical documents developed by subsystem designers and
component designers would be used by software developers to implement required
features in their subsystems.
-
During development, each developer should perform unit test of
their modules to ensure that it’s free of bugs. One of easy method is to
develop module by module. The first gateway module should have a UI, thus the
developer could send or trigger an action on developed codes as unit tests. The
fully tested and working module could be a base to similar modules, i.e.
porting working codes to another module by copy, paste, and update it as
needed.
-
After development of a subsystem completed, developers could
release codes to testers to test the entire subsystem. The Test Case Specification, which is a product document, could be based on any, several, or all technical
documents above. Developer should have a review on written test cases to ensure
full coverage.
-
Overall system tests would be performed when all subsystem were ready.
System Designers should provide feedback on selected test cases, product documents. The overall System Test Specification, a product document, would be based on the
System Design Specification or System
Protocol Specification.
-
During test phases, defects would be logged and redirect to
correct technical staff for resolving issues including release of corrected
codes by developers.
-
After the
overall test phase and critical criteria met, system could be sent to Release Department for deployment.
3.
Subsystem Technical
Documents and Test Specification
A
subsystem could be large enough with many programming modules or blocks. Thus
it will be described by a subsystem protocol specification, technical
specification, technical diagram, or a sequence diagram to illustrate
communications between modules within its subsystem. The subsystem would be
then further break down into smaller technical specification for smaller
components.
A
technical specification document should be details enough for software developers
to implement a feature. Otherwise a flow chart would be a supplement document.
At
Ericsson’s mobile switching department, flow chart of a programming block is
included in addition to a sequence diagram, which describes interaction between
programming blocks. A sequence diagram is like a protocol specification with
fewer details. I would personally drop the flow chart as Ericsson enforced
design rules for each block design and program, thus it is easy to understand.
However a sequence diagram should add more descriptions plus the signal
description.
Usually
there is a Test Specification associated
with a Technical Specification to cover required test cases. The title of
the test specification should match the title of the technical specification, e.g. Outgoing SMTP Technical Specification
would be associated with the Outgoing
SMTP Test Specification.
There should be a subsystem Test
Specification based on the subsystem technical specification, subsystem
protocol specification, or subsystem sequence diagram to verify overall
functionality of the subsystem.
4.
Changes to the Water
Fall methodology
The above process was mostly
taken from the Water Fall methodology with required technical documents passing
to the next phase of software development. However we could change a few things
to make development process faster.
-
Sending
developers or testers to participate in early design meetings instead of
waiting for an official handoff by the preceding phase. For example,
o
A subsystem’s component
expert and a system tester could attend system design meetings for design of a
new feature at System Design level
o
The additional members would provide their inputs or get prepared
for incoming development.
o
The best time to participate would be around 80% completion of a
System Design Specification or a System Protocol Specification, i.e. system
designers and subsystem designers had completed preliminary study and in the
process to write down a solution.
-
Using 15-minute scrum meetings for a technical staff to ask other
team members about current implementation issues to get direction or ideas to
resolve those.
o
Company could implement open door policy, thus any staff could
drop by any office to ask for details or ideas.
o
Each staff should be assigned a project code or pcode to charge
time working on a project. A staff offering help could charge his time with the
pcode used by the other staff. The minimum charged time should be 0.5 hour.
Project manager used pcode to allocate time required for a task as well as for
future estimation of similar tasks.
-
Project manager should ask about project progress less frequently,
but pass by sometimes to offer help or resolve management issues such as
additional resources, unexpected tasks, and unexpected implementation issues.
5.
Mandatory sections
in a document for references and traceability
5.1 Beginning sections in each document
<<<------------------------
1. Introduction
1.1 Purpose1.2 Scope
1.3 Reference
2. Version History
------------------------>>>
The reference section of a document should state the name and
version of document that it is based on. This would provide traceability from
the beginning development process to the end, i.e. starting from a Requirement Specification to a Test Specification.
This also helps to ensure and validate that developers have covered all details
in a requirement specification by a customer.
Sample of a template in a reference section is included below
No.
|
Doc No.
|
Version
|
Date
|
Doc Type
|
Title
|
Author
|
5.2 Version History
Sample of a table including in a revision history section
Version
|
Date
|
Details
|
Author
|
1.1
|
2016-01-22
|
Update
the section xyz for handling of outgoing messages in SMTP protocol
|
XYZ
|
1.2
|
2016-03-15
|
Update
the section abc for handling of incoming messages in SMTP protocol
|
YNY
|
2
|
2016-04-20
|
Final
revision with updates in sections bny and cyz. Product released.
|
YNY
|
2.1
|
This
revision should be the next one for a new feature implementation
|
||
In document version control tool such as SVN, users could add
notes or comments before checking in a document. Users could copy and paste the
version number and revision details of a document in the notes/comments field.
This would help users browsing the repository to search and open a correct
version easily; otherwise users would have to open each document in order to
read the revision history section.
6. Template for a
test case section in a Test Specification and a Test Report
6.1 Sample of a
section in a Test Specification
4.3 < Operating a cooler in a zone >
4.3.1 <Start a cooler in a zone >
Description
|
|
Prerequisites
|
|
Actors
|
Machine Operators or Controllers
|
#
|
Action
|
Expected Results
|
1
|
Open the Starting Engine UI
|
The UI screen is open with all required buttons such
as abc, xyz, etc.
|
2
|
Click the xyz button to start the cooler in the zone
DNY
|
A graph and all
parameters in zone DNY appeared with current data, etc.
|
3
|
etc
|
…
|
- - - - - - - - - - - - - - >>>
With
the reference specified description section in each test case above, we could
validate if the entire technical specification have been covered in this test
specification.Microsoft Word is a good text editor to write a Test Specification. We could insert a picture of UI or a diagram in the document to illustrate steps and procedures outlined in the action and result table.
6.2 Sample of a page in a Test Report in Excel
format
Date
|
March-01-2015
|
|||
Doc name:
|
Operating Engines in a Zone Test Report
|
Revision
|
1.1
|
|
Tester:
|
XYZ
|
|||
Reference:
|
Operating Engines in a Zone Test
Specification
|
Revision
|
1.2
|
|
Statistics
|
||||
Pass
|
12
|
|||
Fail
|
2
|
|||
To be executed
|
23
|
|||
TC #
|
TC Headings
|
P/F
|
Defect
ID |
Comments
|
Function Test Cases
|
n/a
|
P denotes a "pass" test
case
|
||
4.1
|
abc
|
n/a
|
F denotes a "Fail" test
case. The defect was logged and its ID is also included.
|
|
4.1.1
|
abc1
|
P
|
||
4.1.2
|
abc2
|
P
|
||
4.2
|
def
|
n/a
|
||
4.2.1
|
def1
|
x
|
||
4.2.2
|
def2
|
x
|
||
4.3
|
Operating a cooler in a zone
|
n/a
|
||
4.3.1
|
Start cooler in a zone
|
P
|
||
4.3.2
|
Change the cooler temperature to
lower value than the current temperature in a zone
|
F
|
34789
|
The report didn't follow
specification as …
|
4.3.3
|
Change the cooler temperature to
a higher value than the current temperature in a zone
|
n/a
|
This test case is marked as
"n/a", because it is not required to be executed for a reason.
|
|
4.3.4
|
Change the cooler temperature to
the same current temperature value in a zone
|
P
|
||
4.4
|
n/a
|
|||
4.3.4
|
Starting a heater in an exterior
zone
|
x
|
The "x" denotes a "to be executed" test case. Using formula in Excel, we could get the statistics
in the above section.
|
|
The test case headings are the headings in the test specification.
Microsoft didn’t offer to export the headings of a Word document into a file.
However, users could generate headings in a Test Specification, and then copy
and paste those into its associated test report.
An example of an Excel formula to automatically update the number of "Pass" or "P" test cases in the Test Report is COUNTIF(C15:C143,"P")
Tester could also add a section in the test report to describe overall issues encountered in the tests of this object.
An example of an Excel formula to automatically update the number of "Pass" or "P" test cases in the Test Report is COUNTIF(C15:C143,"P")
Tester could also add a section in the test report to describe overall issues encountered in the tests of this object.
7. Cross reference in a defect report
In
the above example, a defect report with ID 34789 was created due to a failure
during execution of the test “Change the cooler temperature to lower value than the
current temperature in a zone”.
The defect report’s title should described the
failure reason and include reproducible scenario for developers to recreate the
failed case and to fix this issue. However, the content of the defect report
should also include the test case title and test specification title of this
failed test for traceability purpose.
8. Other discussions
about software development project
Software
System Development Strategies v1.1 at “https://peterboroughtechservices.blogspot.ca/2017/01/software-system-development-strategies.html"
Packet,
Transaction, or Protocol Programming V1.7 at “https://peterboroughtechservices.blogspot.ca/2017/01/packet-or-protocol-programming-v10.html”
