Project changes and Application documentation

[Sérgio Amorim]

Hi,

First of all thank you for reading this. I need your help on the following. In our company we follow CMMI level 3 maturity process and, one of the items that we must follow is to have the documentation about a project and the documentation about the application.
Imagine the scenario that we already have an app running for 3 years now and the customer asks that a functionality must be changed.
How can we in uml, and particular in EA, address this issue?

My solution are the following, none of them address all my requirements

* I can design changes in two different models, one for the actual changes and another the current state of the app. Not a DRY principle and can lead to errors.
* I use only one model and put annotations everywhere, but if the app is going to suffer plenty of changes there can be annotations everywhere.
* I use only one model and rely on the EA baselines. Unfortunately this is almost like doing a diff on a text file. I can't see, visually, the diagrams before and after, so the visual part of the uml gets lots.

For instance the image below shows the typical bank scenario where the system contains a withdraw functionality and the sponsor now asks that the customer might choose, or not, to print a receipt.



How can I design the diagrams so that the programmer knows what to implement and on the same time he knows what the system does as a whole?

Thank you

[qwerty]

Tough. An idea is to trace <<Change>> elements that explain the kind of change to be applied. The problem here is that your model slowly gets flooded with those. So after baselining again at the end of the implementation you need to remove those changes in order that your model simply reflects the "truth".

You should have a couple of workshops with experts to discuss this matter in detail.

q.

btw: your <<extends>> goes the wrong way. Your Actors use a Realization in direction of a UC. That's nonsense.

[Geert Bellekens]

What we do is keep only one model with the TO-BE situation.
Whenever we do an issue however we make an analysis document that describes in detail all changes needed, with copies of AS-IS and TO-BE as necessary.
We also mark each changed element in EA with the corresponding issue number.
All documents created for this issue (Business Analysis, Scope document, Analysis document) are being attached to the issue.

This allows us to easily find what was changed for which issue.
That is enough for our requirements. We don't even use baselines or version control for our EA model.

Geert

[Sérgio Amorim]

To both, thank you for your help.

Querty: The <<changes>> is almost the same as the putting annotations, so yes, it almost has the sames problems. At each new version it is required to clear that stereotype
Thank you for the "extend" issue, I've done it in a middle of a training session and didn't pay attention to this.

Geert: Glad to hear that others have address this problem and I'm not alone.  
Do you copy the changes to another document, like word or you create another EA project?
How do keep track the changes if the design takes several days so nothing is forgotten?
And, finally, how do you mark the changes? (probably this answers the second question)

Thank you.
/me

[Geert Bellekens]

Hi Sérgio,

When creating our documents we either copy/paste the EA contents manually, or we use the document generator I developed for this client.
Every time we change something we have to mark the change.
Here at this client we use some kind of xml-like tags in the notes field.
So our notes fields look something like:

Code: [Select]

<version>17.34</version>
<definition>De (her)indiening van de betalingen naar het fonds voor bestaanszekerheid metaal (FBZMN) voor de combinatie van C10maand, werkloosheidsmaand, lid en kaarttype.</definition>
<description>De indiening kan zowel gelden voor normale betalingen als voor bijkomende betalingen (ComplementPayment).
Het bedrag dat gecommuniceerd wordt met het fonds is de som van alle Payments, ComplementPayments en Recuperations die gelink zijn aan de introductie.</description>
<rationale>Dit type zorgt ervoor dat we het goedkeuringsprocess voor de betalingen voor het fonds metaal (FADEO) kunnen opvolgen.</rationale>
<changed workitem="50217" user="t99gbk" date="09/12/2011" status="changed">Constraint "Total amount must be total amount of rejection base" up to date gebracht</changed>
<changed date="22/07/2011" workitem="na" user="t99gbk" status="changed">documentatie aangepast</changed>
<changed date="02/07/2010" workitem="38439" user="t99gbk" status="changed">attribuut MonthYearUnemploymentMonth: type en naam gewijgd naar UnemploymentMonthKind</changed>
<changed date="01/07/2010" workitem="38439" user="t99gbk" status="changed">attributen HasWorkResumed en IsInterventionRequired verwijderd en attributen ReasonIncompleteMonth en DeductionAmountRSZ toegevoegd</changed>
<changed date="22/04/2010" workitem="29417" user="t99gbk" status="changed">relatie naar UnemploymentMonth vervangen door attribuut MonthYearTypeUnemploymentMonth</changed>
<changed date="14/01/2010" workitem="29417" user="t99gbk" status="new">nieuw aangemaakt, vervangt de IntroductionFADEO</changed>I've written an add-in that allows our users to read/edit these tags in a more user friendly manner, so we only use the notes field through this add-in.

The <changed> tags are used to make all changes to an element, and the workitem = "29417" containt he ID of the change.

We have defined an SQL search that also uses this to find all changes for a certain workitem, and our document generator also uses this search to select the elements to put into the document.

But of course, if an analyst forgets to mark his changes along the way, there not much our tooling can do about it.

Geert

PS. I didn't design this way of working, and I doubt if I would implement it this way at a new client, but with the toolset we have now it is an acceptable way of working.

[Sérgio Amorim]

Thanks. I'm new in EA so I still have a long walk to do, but certainly you help me to find a path.

I invite everyone else to show the community how they address this issue: Design and know what changes happen in project revision X on an application Y using DRY principle.

[Paulus]

Hi Sérgio,

I have found that the following works very nicely for documenting changes to diagrams:

For each change:

1) Create a document artifact
2) Place this on each diagram that is modified for this change, and link the change to the diagram elements that are changed (dependency relation)
3) Provide additional info in the label of such dependency relations, like eg 'added field xyz', 'included alt flow UVW', ...
4) Use a script to generate an RTF document that contains all diagrams that include a change => this can be used for formal change approval
5) Generate a static website from the model => this can be used for fast browsing when trying to understand the scope of the changes in the RTF document
6) When starting a new release: freeze the static website as release documentation and -delete- the document artifacts created in step 1 (this removes all references to the change in the model)
best regards,

Paulus