transitioning our toolkit
TRANSCRIPT
Transitioning our Toolkit
iress.com
Andrew Williams – Lead Product Analyst
April 2015
The movement to integrated document management
Agenda
In this session I intend to cover how we have taken the traditional analysis and design tools and changed
the way in which they are used, to provide an integrated approach to document management, which
reduces inconsistences in our documents and takes the effort out of generating new versions of
documentation.
This session will focus on:
• An introduction to IRESS.
• Then – how we used to document the systems that we built and the challenges it gave us.
• Now – an insight into our new approach.
• Conclusion
iress.com 3
Setting the Scene
iress.com 4
An Introduction to IRESS
Here at IRESS we are passionate about creating market leading technology solutions. Within the UK we
currently providing solutions in the following spaces:
• Sourcing Systems – The Exchange and Trigold Prospectors enable financial advisors to source
products within the UK financial services industry.
• Wealth Management Systems – XPLAN, Advisor Office and Momentum enable wealth managers,
investment advice firms and mortgage brokers to operate efficiently, profitably and compliantly in the
post-RDR world.
• Mortgage Sales and Originations – Internally referred to as MSO, this enterprise mortgage solution
manages the process from initial enquiry through to release of funds and completion.
Personally, I have been working for IRESS for over 3 years on various implementations of MSO, having
previously worked for a local Building Society in a variety of roles.
iress.com 5
An Introduction to IRESS
The Lending division of IRESS, who are responsible for all of the Mortgage Sales and Originations
solutions were originally N4 solutions, then Avelo before becoming part of the global IRESS family.
Whilst N4 and Avelo, the focus of the organisation was to produce stand alone sales solutions for the
financial planning, insurance and mortgage markets, as well as, custom implementations of MSO.
Since becoming part of IRESS, the focus has been switched to make us a product company, as there
has been internal investment in building a version II Mortgage Sales and Originations solution which will
be a true product, with multiple implementations of a single code base appropriately configured for each
Lender.
It was this move towards constructing a product which started us thinking, what are the requirements for
documentation to aid construction and testing of MSO Product and what are the needs of our clients, in
terms of understanding the behaviours and configuration options?
With this question in mind, it was important to assess whether the tools in our toolkit were the right ones
and were we using them to their full potential.
iress.com 6
The Old Way
iress.com 7
Old documentation approach
Overtime we have naturally
been evolving the approach to
the way in which we gather
requirements and how we
complete the functional design.
This has historically varied by
both client and implementation
team, this diagram illustrates
what was produced.
IRESS
iress.com 8
Old documentation approach
Data Content Specification:
An excel spreadsheet per module, containing 15 columns of
information including:
• Screen Name
• Label
• Layout details
• Type
• Validation Rules
• Data Mapping
Functional Specification:
Word document which contains:
• A high level activity flow (at the level of 1 activity per screen)
• Textual description of each screen including details of any
additional business processes or special processing which is
completed
• Traceability matrix for requirements included in the document.
iress.com 9
Old documentation approach
For our FPPOS (Financial Planning Point of Sale) solution a more visual approach to
documentation was taken.
Wireframes:
Using Axure wireframes, a representation of the actual screens were constructed.
These were prototypes, which contained:
• The actual branding of the site
• The layout of the screens
• Widget properties which contained specific information about each field (i.e.
applicability rules, notes, data type, minimum/maximum restrictions.)
These were available as an html website and a Word document.
Functional Specification:
Word document which contains:
• Textual description of each screen including details of any additional business
processes or special processing
• Details of all calculations which are performed by the system
iress.com 10
Old documentation approach
For our MSO solution a slightly different approach was taken:
Data Content Specification:
A Word document per module, containing a table (and some narrative).
Functional Specification:
We invested in a new tool, Enterprise Architect from Sparx. This was used to draw
use case and activity diagrams, which were then copied/resized/split across pages
and pasted into the functional specification Word document. (Essentially, we were
using it to draw pictures). These activity diagrams effectively showed the data
capture process with the workflow and service interactions.
The Word document also contained:
• Textual description of each process.
• References to messages and parameters.
Catalogues:
With MSO there are a number of additional catalogues:
• Rules and Parameters – values for each parameter and pseudo code
representation of the rules.
• Messages – text of message and notes of where used
• Case Events – audit events of things which happen.
iress.com 11
Other Factors
In addition to our established
documentation approach for each
product, we have an SDLC process
which has an effect on the
documentation that we produce.
This process means that as part of
the development process we need
to produce requirements, estimates
and some form of functional design
specification.
Tool that our SDLC processes were
built around, from managing our
requirements, through tracing to test
cases and defect management.
SharePoint services for TFS were
also to be used to store documents.
iress.com 12
Summary of toolkit
• Requirements Definition
• Functional Specification
• Data Content Specification
• Data Content Specification
• Catalogues
• Requirements
• Wireframes
• UML Diagrams
• Document Storage
iress.com 13
Weaknesses with old approach
• Different approach per
solution/team, therefore difficult
to move resource between
projects.
• To ensure that Document A
which references item X in
document B, mentions item X
need to manually complete
cross checking.
• Functional Specification Word
documents and Excel
documents are stored in
SharePoint, therefore limiting
updates to a single user.
• Use Case / Activity diagrams
are manually copied/pasted
into Word from EA, therefore
changing diagrams requires a 2
step process.
• Long winded manual process
to impact assess change
without in-depth knowledge.
• Ability to impact assess change
is very difficult as scanning such
a range of document types is a
manual task.
• Inconsistences between 2
documents causes more rework
and costs more.
Maintenance Time Consistency
iress.com 14
Transitioning Forward (part 1)
iress.com 15
Transitioning Forward
With the decision to move forward and build MSO Product we decided that we needed to review / agree
the approach to our documentation. The development was to follow our SDLC process following a
waterfall approach and TFS must be used for requirements. We selected the following options:
• The feedback that we had had from the FPPOS team was the client’s really
like the visual representation of what they were actually going to get.
• Developers found it easy to code from, easier than data content specs.
• As some of our product has processes without a UI, then we decided that we would
need to produce process diagrams.
• Tool that our SDLC processes were built around, from managing
our requirements, through tracing to test cases and defect
management.
• Document management solution which was already in place for storing and
managing versions of documents.
iress.com 16
Transitioning Forward
Consistency 1. A documentation set which
was consistent with itself.
2. Diagrams/Documents with
consistent styling.
Traceability
1. Ability to be able to find where
parameters, messages, reference data,
data items were used easily
Usability 1. Documentation which told our
customers how the system
actually worked.
2. A format which was easy to
understand for customers and
colleagues.
Improved Efficiency
2. Reduce the time spent producing
documentation.
So having selected our tools, what were we hoping to achieve?
iress.com 17
Requirement Management
• Requirements were
created and published
into TFS
• Requirements exported into a file and
mail merged into a Word document to
produce a client-friendly Requirements
Definition document
• Requirements Definition stored in
SharePoint.
As part of our objective to improve efficiency we looked at how we could integrate the tools together. We
tackled this first with requirements.
iress.com 18
Functional Specification The next area that we tackled was the functional specification, including traceability of processes to
requirements. One of the biggest issues with the old process was the fact that we were constructing the
activity diagrams in Enterprise Architect, but then manually copying/cropping these into the Word
documents (where we were then maintaining the narrative).
For anyone who has used the in-built documentation generation tool in EA, we quickly realised that this
was not going to give us what we needed, therefore we looked into a new tool. We picked eaDocX.
This gave us the ability to produce professional documents in our IRESS templates with a high level of
customisation. But most importantly, it gave us the ability to be able to have a single version of the truth,
in that we maintained the use case/activity diagrams (with narrative) in EA and then generated several
different documents for different audiences with the same content, without all of the manual copying,
pasting and cropping.
iress.com 19
Functional Specification
• Requirements were
created and published
into TFS
• Requirements
exported into a file
and imported into
EA.
• Functional Design Spec
stored in SharePoint.
With eaDocX now added to our toolkit, we were now able to automate the generation of our Functional
Specifications from EA, including traceability matrices.
• Profile configured in eaDocX to
generate a document which include
use cases/activity details.
• Profile configured to include matrix of
requirements to processes.
• .docx generated
iress.com 20
Catalogues
• We have deployed EA against a SQL Server,
therefore it is possible to write a SQL statement
against the database to report out the
configuration.
• These queries are then embedded into Excel.
• Functional Design Spec
stored in SharePoint.
The next artefact to work on was the configuration catalogues that we needed to produce. As part of our
review of EA usage we decided that we would store the configuration artefacts in EA and link them to
diagrams as appropriate. Thus we should be able to identify where configuration items were used in EA
diagrams. To get this out we decided to automate the extraction.
iress.com 21
Wireframes Wireframes were produced to show what the screens looked like, each field was annotated
with widget properties.
iress.com 22
Customer feedback
Wireframes “because all fields are always
shown, it is difficult to actually see what the screen will look like”
“I have to click on every field in turn to be able to see the widget
properties”
“I have to lookup the message text or parameter values in another
document”
FDS “The process diagrams duplicate (sometimes
contradict) the wireframes”
“I have to cross reference too many documents”
RD “does as per its name,
defines our requirements.”
Catalogues “I like the ‘Where Used’ column as I understand the context when deciding on the value, shame it
doesn’t include cross references to the wireframes”
“There are instances where not all of the
parameters are consistent, it looks like documents have been generated at different times”
“There are too many, couldn’t they all be
combined?”
With work underway it was important to get feedback on what had been produced.
General theme: Better than original approach,
but still issues.
iress.com 23
Transitioning Forward (part 2)
iress.com 24
Transitioning Forward (again)
Following the feedback from clients and a change of focus within IRESS, we had the opportunity to
review the toolkit again and the approach. For this latest iteration we decided that we would use an Agile
approach and we were free to choose the tools that we used. One of the principles that we adopted was
taken from the Government Service Design Manual of:
Discovery Alpha Beta
Essentially, this approach starts with a short discovery phase whereby the team have been able to
research and explore the user story. Followed by a short phase of prototyping solutions, before moving
into building for the demands of a live environment.
iress.com 25
Transitioning Forward (again)
So how did this affect our toolkit?
REMOVED
• By adopting an Agile approach and the Discovery, Alpha, Beta process, we
removed the need to spend a large amount of time building upfront
wireframes.
• Also, based on feedback, the wireframes didn’t seem to meet customers’
needs.
REPLACED WITH:
• During our discovery phrase we used (use) hand drawn sketches or white
board illustrations.
• In parallel we started to define a data contract. A data contract is the
definition of the actual data, the business rules for applicability,
minimum/maximum, data type, caption etc.
• Document management solution which was already in place for storing and
managing versions of documents. Does an OK job, so CONTINUE.
iress.com 26
Transitioning Forward (again)
So how did this affect our toolkit?
KEEP, BUT LOOK TO DO MORE WITH IT
• The feedback for the FDS was really positive therefore continue with these
tools. However, we need to address the following points:
• We need to avoid duplicating content which is in the data contracts.
• We need to use more of the EA and eaDocX functionality.
• We need to produce self-contained functional specifications (i.e. for a
module we include all of the messages, parameters, interfaces)
• By working in an Agile approach we have traded requirements for a backlog.
However, as we are new to Agile, we decided to track this in Excel. So
REMOVED.
iress.com 27
The new framework
Having selected our tools, we now needed to decide on how best to use them. Introducing our
documentation framework:
• Data Contracts stored
in SQL Server database
• EA configured to store content
in SQL Server database
• A validation framework whereby every
night we run a number of queries
against the data contracts and EA
content to highlight errors. These then
get emailed to the teams, so they can
be fixed as soon as possible. (150+
checks)
• A layer of views, stored procedures
and functions created within the
database to combine the data
contracts and EA content to allow
intelligent documents to be generated.
iress.com 28
Demonstration
iress.com 29
Conclusions
iress.com 30
Conclusions
The journey that we have been on has meant that we have added eaDocX to our toolkit, changed the way in which we
have used some of our tools and stopped using others. Although, we would keep all of them in there – as you never know
when we will need to transition our toolkit again.
Thank you
iress.com
1 – 8 Priory Court
Poulton
Cirencester
Gloucestershire
GL7 5JB
T: ++ 44 (0) 1285 852200
Andrew Williams BSc (Hons)