Mapping the Software Development Lifecycle
Mapping the Software Development Life Cycle (SDLC) to
the Software User Assistance Development Life Cycle
At the end of these seven phases, you will establish what
your customer requires the UA system to do, and how you will achieve it by
defining a clear path for its development, testing, and its management, thus making it a
quality UA system.
Note the tasks pertinent to each Phase of the Software
User Assistance Development Life Cycle are explained in the following chapters. At times,
some tasks overlap tasks in other Phases of the life cycle.
First Phase: Capture Software UA Requirements
Capture your customer requirements in a UA Requirements
Specification document.
Identify Your Customer
Know what your customer wants today as well as tomorrow.
Knowing your customer’s future requirements ensures less rework on your design. Use
communication to your advantage.
- Ask questions, more questions, and even more questions.
- Use diagrams
- Receive constant feedback
Phase 2: Analyze UA Requirements
Analyze the requirements to gain a deeper, more technical
understanding of them. Understand where and how your UA system will be used. Will it be
used in hospital laboratories or IT departments? What is the data retrieval time for your
UA system? Record this information for your UA design. Hospital laboratories could have
dim lighting and the data retrieval time from your UA system could be less than 3 seconds!
Design your
UA system based on modular components. Modular UA systems can be plugged and unplugged as
required. They also ensure easier maintenance, tighter security, enabling access rights,
and easier licensing. Paper-based UA systems carry a chapter related numbering. This makes
printing and binding cost effective.
Consider the following parameters when designing your UA
system.
- Choosing
the Platform – Platform-independent or platform-specific.
- Choosing
the Familiar – There always is a strong temptation to choose what you are
familiar with. Although it is difficult to be objective, it is always to ask other people
for opinions, especially individuals who do not have exactly the same preferences as you
do.
- Future
Proofing – All the same, for a long-term software application, your design for
its UA system must be based on future considerations. Study the UA system’s survival
capacity. Use new innovations that are likely to stabilize in the future. For example, if
you choose an authoring tool provided by a single supplier, what is the likelihood of that
supplier being around in the next five to ten years?
- Changing
Technologies – Is the technology used for your UA system likely to change?
- Including
Modularity – Keeping pace with changing technologies lies in an accurate analysis
of your UA system’s functional requirements. Therefore, design with a high degree of
modularity and try to encapsulate each module so that it presents a well-defined user
interface. Everything else must be hidden. This approach enables you to adapt to changing
technologies by simply unplugging one module and replacing it with another that makes use
of the new technology.
- Using
a Simple Model – Above all, create a simple design for your UA system.
Always include the software application’s Domain Business Logic into your design. The
business logic will be required later for access restrictions through licensing of certain
modules of the software application, thereby impacting the UA system’s modules. At
times, your UA system might need to have an Input User Query module, an Output Result
module (handling the user interface, and a Database Access module (containing the
data-processing module with the business logic). Your UA system might end up having a
Client-Server design that could be a Single-Tier or a Three-Tier model!
Develop each UA system’s module as an independent
entity that can be tested in isolation, to enable verification of its content and
functionality.
For this methodology to work, you need a project plan for
each project you undertake.
Your plan must be capable of providing the
following:
- Clearly
identified resources throughout the life of the UA system project.
- Built-in
contingency time to allow you to manage problems without affecting the key
delivery dates.
- Well-defined
milestones to represent key dates by when you must deliver certain deliverables.
Milestones are vital for monitoring progress.
- Clearly
identified dependencies indicating both your responsibilities and the
customer’s responsibilities.
- Tracking
mechanisms to track your UA system’s development and the team’s progress.
- Identification
of Risks and Risk Assessments for the entire life of the UA system.
Ensure reusability of the UA system by developing
independent modules in it.
Create a prototype of your UA system and get a go-ahead
from your customer.
In general, projects rarely run
smoothly. Always make room to handle complications.
- Contingency
Time – This time provides the slack that lets you handle complications –
up to a certain point. If you have contingency time due to an early completion of your UA
system, store it; do not waste it. Contingency time is one of the main arrows in a team
lead’s quiver to handle complications.
- Resources
– Keep them happy. Plan variation in their work. Some UA creators are better than
others – some are good at content creation, some are good teachers, some good at
finding bugs – some good at technology. Identify the strengths and weaknesses of each
resource. When a complication arises, you know the best resource who can react to the
issue.
- Small
Teams – The advantage in a small UA team is – everyone knows what the
other is doing. It brings about a focused team spirit and when complications arise, team
members pitch in to solve the issue. This spirit is less obvious in large UA teams, where
each member has a smaller identity. Another character of small teams is that they are
faster to react to complications than bigger teams.
- Leading
a UA Team – A team is only as good as its leader! The Team Lead must have primary
management control of the UA component of the software application. Generally, a
Team Lead addresses technical issues; consequently he or she must also have good knowledge
of the UA authoring tools, the UA system, as well as the software application.
- Escalation
Chain – Every UA system project must create an Escalation Chain. The project
needs a means by which issues can be moved, or escalated, through a series of levels, with
each level involving more senior project members both from the UA system and the software
application. The underlying principle is that if you are not able to resolve an issue, the
person up in the chain is likely to have more experience and influence to do so. That
person may not always be able to solve your issue directly, but he or she can point you in
the right direction.
- Replanning
– In extreme cases, certain complications in the software application’s project
might need you to replan part, or even the entire project. Replanning a project in
progress is very difficult. Many activities may have already started, some activities may
be complete, and some may be nearing completion. Attrition of resources belonging to a
project is also a possibility. Replanning a project is like hitting a moving target.
Managing changes to the design of
the UA system is critical. Use an efficient change management tool like Caliber to record
these changes and note the reason for changes.
At times, the customer may not fully appreciate what the
requirements are until the system materializes and the customer starts using it. If that
happens, someone failed to capture the requirements in a way that highlighted the
customer’s true needs. By this, I mean the customer in some way changes the basic
definition of the project. This could have a devastating effect on the timetable if the
change is not handled correctly.
- Changing
the Requirements – In the Requirements Capturing phase, you have found out what
the customer’s future requirements will be, if you have done this right, you
understand where the customer eventually wants to go with the UA system that you are ready
to develop. Chances are that the goal posts will shake, but not move, as the project
progresses.
- Changing
the Schedules – If you find the Customer demands it, but you must be aware that
you have only a certain number of resources and a limited capability. In all probability,
the changes in schedules were a result of late deliveries of the software application in
the first place!
- Managing
the Customer – In addition to managing the project, you must also manage the
customer. The Customer, being the king, would need a lot of consideration. Have a
strong contractual platform in place on which you can conduct negotiations; you can then
manage the customer’s expectations, demands, and concerns. Your ability to manage the
customer will be only as good as the tools you use. At times, you might have to give, and
at times, you might have to take.
- Strong
Contractual Platform – Have a strong contractual platform from which to conduct
negotiations, you can manage the customer’s expectations, demands, and concerns. Your
ability to handle the customer will be only as good as the tools available to you.
Sometimes, you have to give, and, sometimes, you have to take. Being tough is sometimes
necessary to manage a customer who might turn up with unrealistic expectations. At the
same time, giving in a little here and there would fetch you a reputation of being
flexible, and then when the time comes for some help from the customer, you will find
people are more willing.
- New
Requirements – Assess new requirements. Always ensure that they do not compromise
the current design of your UA system.
Integrate
all the developed UA modules, and test the completed system as a whole. Then, integrate it
with the software application and test it again.
Ensure that UA Testing and UA Support is part of the UA
system’s life cycle.
- Manual
Testing – The UA creator manually clicks hyperlinks (online) and checks
cross-references (paper-based).
- Automated
Testing – Try to set up a batch of tests of whatever you would do manually,
and get the results into a file. Run this batch file at the end of your workday and see
the results file the next morning. You could also get hold of a good automation package
like Rational Robot or Test Director that would provide you with the details of the tests
performed.
- Regression
Testing – A version control tool such as Visual Source Safe or Rational
Clearcase tracks changes and ensures that a previous version of the UA system does not
overwrite newer versions and allow old bugs to creep in. Perform sufficient tests to
ensure that a new fix has not affected previously working functionality, but when in
doubt, test the entire UA system.
- Automation
of Test Scripts – Use test scripts provided with a testing software to achieve
the desired result.
- Alpha
Testing – Test each UA module, then integrate the modules and test their
functioning. After this, perform testing at the system level. Integrate with the software
application and test again. Test the UA system live for the very first time in a
controlled environment. Always have a mechanism to fall back on the old UA system, if
things go wrong.
- Beta
Testing – In this phase, set up the UA system in the live environment (that is,
the customer site!) to experience the full range of operational conditions.
- System
Testing – This will be your ultimate test when the software application goes live
along with the UA system.
Quality is not just about
testing. Quality must invade every aspect of the project. Make Quality part of the entire
process. Following are the keys to Quality.
- High
Degree of Consistency – Ensure the presence and implementation of systems and
procedures that guarantee a high degree of consistency in each phase of the Software UA
Development Life Cycle.
- Set
of Written Standards – Maintain a set of written standards that determine how the
UA system must pass through the different phases of its life cycle and the result of each
phase is controlled.
- Auditing
Practices – Conduct periodic audits to ensure adherence to standards, and keep
the records to prove adherence to external auditors.
- High
Degree of Accountability – Build a high degree of accountability for each team
member. Also record the results at each decision point in the UA system’s lifecycle.
- Lessons
Learnt Survey – Get everyone on the team to fill in a Lessons Learnt Survey that
will help determine what went well, and what went wrong. This record can later be used to
ensure that errors and mistakes from previous projects are not repeated in future
projects.
- QA
Policing Methods – Define QA standards for your UA system, and also identify the
standards that will be policed.
Implement
the completed, fully tested UA system for the customer, and allow the customer to perform
formal acceptance testing.
Installation - During installation
of the UA system, ensure that the correct .DLLs, multimedia controls, multimedia files,
java scripts, etc. are packaged with the software application, and are deployed correctly.
Licensing & Access Rights – The licensing and
access rights aspect you considered in your UA design, will be put to use now. Some
modules of the UA system need to be linked to the licensing or access providing rights of
the software application. For example, the online user assistance for a Security or a
Configuration module must not be available to all.
- Acceptance
Testing – This does not mean that the UA system is absolutely ‘bug
free’. It merely means that the testing did not reveal any more bugs.
- Wrapping
up Acceptance – Ensure that a signed document from the customer closes the
Acceptance Testing of the UA system.
Set up a
support and maintenance capability for the completed UA system. You might need to make
patch releases along side scheduled releases.
The following types of issues may
be reported at your software application’s helpdesk.
- Finger
Trouble - Issues reported by inexperienced users who do not completely understand how
the UA system works.
- Genuine
Bugs: Issues that require technical solutions by support or development staff.
- Environmental
Issues - Issues associated with high-end PC-hardware and different middleware or
operating-software environments.
- Wish
List – Issues that clearly request for additional functionality beyond what was
contractually agreed upon.
Setting
up Support
Set up
a single channel to report user-assistance related issues. You implement different types
of support and generate revenue from support. This can be a good revenue stream.
- Education
- Standby (Customer’s Helpdesk)
- 24x7 Support
- Support Call Handling
Security
Customers may appreciate support desks freely logging on
to their systems. Even remote access may be difficult to obtain. In such cases, use a
Dial-Back Facility or email for support.
Security of a software application cannot be taken
lightly. A customer’s software can never be at risk in an endeavor to solve a support
issue.
Maintenance typically follow patch updates or scheduled
releases.
- Patches
– Sending an upgraded executable or binary file to fix the fault might be a great
idea. But remember to keep track of which fix was released to which customer.
- Scheduled
Releases – You do not want to add patches to the same UA system at different
customer sites. Avoid falling into the loop of adding patch after patch. Adopt a policy of
releasing patches only when absolutely necessary. All customer sites will not have the
same patch level. Issue a maintenance release of your user assistance system (online and
paper-based).
Splitting projects into well-defined phases is essential
for planning and management. The following are key attributes for a phased approach.
- Tangible
Deliverables At the End of Each Phase – Ensure that the deliverable is verified
and consistent across the deliverables from previous phases.
- Iteration
– Iteration-based development is the key in ensuring consistency across phases.
Create a prototype. Have a preliminary concept meeting to
kick-start the process. You may receive requirements via a Functionality Overview
document, meetings, a long list of requirements on paper, hand-drawn diagrams,
ill-prepared presentations, conference calls etc.
In this phase, work on the following parameters:
- Key
Functional Requirements – Identify them for your UA system.
- Major
Areas of Functionality & Content – Define them at a high level.
- Complexity
of Software Application – Gauge the complexity of the software application to
help you understand the complexity of your UA system.
- List
of Dependencies – Draw up a list of dependencies, stakeholders, and content
providers.
- Areas
of Risks – Identify risk during the life of your UA system.
Based on your preliminary study of the requirements and
analysis, draw up a list of activities that must be executed to complete the UA system, as
you understand it.
These activities must include the following, but need not
be limited to them.
- Capturing
requirements.
- Analyzing
the requirements.
- Designing
a modular UA system to fulfill the requirements, both immediate and future.
- Testing
the modular UA system.
- Integrating
the UA system with the software application.
- Installing
it at the customer site.
- Getting
customer acceptance.
- Reviewing
all Software UA System Development Life Cycle outputs.
- Verifying
the iterations of all phases.
- Developing
formal testing specifications.
- Managing
the entire UA system from start to finish.
For each of the activities you have listed, you now need
to develop an estimate. Estimates consist of the following:
- The
maximum time you think the activity requires for its completion.
- The
minimum time you think the activity requires for its completion.
- The
range, max-min, which suggests the level of uncertainty in the estimate.
- The
type of resources required – for example, UA system team, analysts, testers, and so
on.
The idea behind the max-min approach is that you provide
a range of effort you believe a particular activity will require; this range indicates
your degree of uncertainty in the estimate.
The
breakdown of the software’s required functionality into self-contained, functional
entities allows you to estimate for the design and development activities with a
reasonable level of precision. You can supply a max-min figure for each individual module
and summarize the figures to establish numbers for the complete activity.
You can identify potential risks.
Risks may vary financial or technical risks, or other risks.
Conduct or propose feasibility
studies to minimize technical risks. For other risks, find suitable action to
minimize the risk, or take those risks into account in your project plans and estimates.
You would need to consistency
monitor progress. Use a good tool such as MS Project or Primavera.
You need documentation right through the life of the UA
system. Some of them are:
- UA System Terms of Reference (Your terms of reference
would be the software application for which you are developing the UA system.)
- Contractual Correspondence File
- Non-Contractual Correspondence File
- UA System Project Plans
- UA System Quality Plans
- UA System Requirements Specification
- UA System Design Specifications
- UA System Test Scripts and Results
- UA System Risk Assessment and Analysis Reports
- UA System Issue Log
- UA System Change Log
- UA System Reviews
- UA System Audit Reports
You need a mechanism in place for issue management. A
simple excel spreadsheet containing the pertinent information could do the job well.
- Record all issues in an Issue Log.
- Identify an owner for each issue.
- Monitor the Issue Log regularly, and periodically reassess
each issue in terms of its impact on the project.
- Set a priority for each issue, in terms of its timeframe
for resolution, etc. This can be altered according to the circumstances.
- Inform all relevant stakeholders of the issues and their
status.
You need to streamline change requests into the
development of your UA system.
- Initiate
all changes with a formal change request and record it in the UA system’s Change Log.
- Assess
and prioritize all change requests.
- Authorize
all changes that are to be implemented by the relevant stakeholders, and then properly
plan them into your UA system’s development.
Ensure all changes are implemented and completed in a
controlled manner.
Create a culture based on
success. If each team member believes in on-time delivery, you are most likely to meet
your dates. A culture based on success can evolve only if that success is repeated .
Follow a methodology that achieves a high degree of consistency across a team composed of
many people with different levels of ability, enthusiasm, commitment, and so on.
A User Assistance system project is a team effort. You
being a team lead have responsibilities to each team member, and vice versa. The
collective commitment, ability, productivity, and attitude of each team member will
determine a UA system project’s success. The project will be only as strong as its
weakest link. If you think that the creation of a UA system is difficult, just think about
what the software application’s project management requires to turn an idea into a
software application.
About the Author
Tamara Ferris is currently a Lead
Technical Writer with Siemens Information Systems Limited and has close to eight years
experience in the technical communication industry. She has worked extensively on Online
User Assistance systems.
You can write to her at Tamara.Ferris at siemens
dot com or Tamara.Ferris at gmail dot com.
Your Thoughts?
What are your thoughts on this? Drop me a line at ivan
at klariti dot com |
I'm Ivan Walsh, the person behind this site. I help people improve how they write, publish and extend their business assets.