How to jump to Use Case docs?

[mwra]

I've RTFM so sorry if I've missed something.

I'm working primarily with Use Case aspects and spend much time jumping between UC diagrams and the word docs holding the actual UC.  Once the doc is linked it is still 5 clicks to open the doc.  Is there a faster way.  Can I put a menu call to linked (docs) on diagram context menus.

I realise for some people there may be many docs but for me it is one linked doc per UC.

The other painful process is creating the links.  It would be nice if I could use a Doc naming schema such that I could point EA a a folder (or folderset) and let is auto-discover and link the UCs.

When exporting to HTML, it would be useful if links to DOCs could run a shellexecute routine to call Word (or whatever) rather than cause the browser to start a file d/l.

Although my needs only sctrach the surface of EA's features, it's a neat tool.  Thanks, Sparx

Regards

Mark A

[jaimeglz]

Hi, Mark.

To get to your document in just one click, I would suggest using a hyperkink: use the tool with the geared wheels (it is in the third line of the menu bar in EA 3.10, to the right the add notes icons).

Having said this, let me ask: Why have the use case in a word document, appart from EA? It is much more efficient to do it the other way around: Have the use case described in EA (use the scenarios tab, or other features of the use case dialog) and then have EA generate an RTF document with your use case description.

I hope this works for you, since you may have imortant reasons to do things the way you are doing it.

Jaime Gonzalez

[mwra]

Jaime,

Thanks.  Problem is I'm not making the model - I'm a domain expert (whatever that is) who's been given the tool so he can look at the diagrams and UCS providing domain expertise.  I'm not really supposed to be able to alter things.  I have set up links to the UC DOCs via the properties.  

Having a hyperlink per UC is a lot of extra UI-based work (>100 links) to connect something that's already connected in the properties.  Anyway, exported to HTML the UC links to the Doc just fine without a hyperlink.  It just feels like there's a menu option I've missed.

As to putting the UC in  EA, the properties dialog doesn't seem to have the fields I'm looking for.  We're using business level UC at this early stage and the sections are Overview, Actors, Preconditions, (Normal) Scenario, Post-conditions, Supporting Info and Requirements.  The EA Properties dialog has different labels.  I can find a home for the UC Title and the Scenarios - but where for instance is the list of Actors?

Am I making sense here?

Regards

Mark

[jaimeglz]

Hi Mark,

Yes, what you are saying makes sense. Let's see if this helps:

1. You have an obvious place for Overview and Scenarios in the Use Case dialog. Just note that there is a "Type" drop-down list box in the Scenario tab, where you can choose wheter it is the basic path (what you call "Normal") or some variant.

2. Actors. When you create the "uses" association between the actor and the use case, this association is automatically listed under the "Links" tab in the use case dialog. These links will be listed in your RTF or HTML documentation, as well.

Keep in mind that an actor can play roles in several use cases, so it is not necessarily tied to a particular one. The way I handle this is by creating an "Organization" (you can call it "Actors", or "Personnell") package either under the root of the project, or under use cases. I store all the actors, workers, people, diverse fauna elements and the Org Chart diagram under this package: the advantage is that I have a single, clear place to look for "xyz manager" or "user" actors and workers. Once you create them, just drag and drop these actors into your use case diagrams.

If the actor is a machine (for instance, a FAX) or a system, it should be grouped under the components or deployment model, and added as a chapter into your RTF of HTML documentation.

3. Preconditions and Post-conditions go under the Constraints tab. See the "Type" drop-down menu under this tab.

7. Supporting Info. If these are separate files, use the "Files" tab to document this info. However, these will not appear in your RTF or HTML docs.

8. Requirements. Use the "Responsiblity" tab (and see "Requirements" in help, on how EA handles these).

Once you have made one or two use cases, do try to generate your RTF or HTML docs, and play with the options.

Hope this works.

Jaime

[Steve_Straley]

Jamie,

PMFJI, but there are a couple of RUP-based items missing.  For example, there are sub flows off alternative flows in addition to just plain subflows.   There are also "extension" points.   This is why I'm trying to add a supplemental tool to take what is in EA and map it to RUP-based documents.   I think if EA can "tout" RUP-support, then EA will have more sales.   For some reason, corporate types talk RUP and think ONLY Rose Suite can do the job.

Just my .02

Steve

[mwra]

Jaime,

Thank you, it's beginning to make sense.  One last question, if I may.  

It seems I can only create documentation for a package, not a single UC inside a package.  If I select a UC in the 'Workspace' treeview window neither the main menus or the context menu have a 'Documentation' option such as on a package's context menu.  If I make a change to one UC I'd prefer not to export all package docs.

Thanks again,

Mark

[jaimeglz]

Hi Steve, hi Mark.

I don't know if this is the best way of doing it (and I'm sure there could be better ideas from our lively forum community), but here's the way I do it :

I generate documentation only after I am satisfied with my model, so I have not found a situation in which I have to generate an RTF or HTML for a single use case.

I begin by creating an ordinary RTF document (outside of EA) with the front page, a page for the TOC, and an introduction. I open this document, go to EA, generate the RTF with my model, and copy and paste it into the doc with the front page and TOC. After updating the TOC, I save this new document with a version number (for example, CONTAB03.RTF).

Here is where your point is very valid, becuase after I generate the docs, there are endless addtitions and corrections. So I give the RTF a detailed reading, but I make all the corrections in EA (I never make corrections to the RTF, except for the introduction).

I generate again, with the corrections, copy and paste into the RTF with the front page and TOC..., save both the EA project and the new RTF with a new version number (CONTAB04.EAP, CONTAB04.RTF).

When there are several of us working on a single project, I version each package, and then export it and send it by EMail to the analyst responsible for that package.

After I'm satisfied, I EMail or send a CD with the whole enchilada (EA + RTF) to my friend Alberto ("El Charifas"), who takes care of quality control, and gets both the EA project and the RTF (or HTML) ready to turn it in to the customer.

It sounds a bit inneficient to generate docs only for the whole project, this way there is no confusion. We've just documented a big accounting system, and generating the whole use case package takes a little longer than a minute (and it is quite big, because it has JPG "pictures" of all the screens and windows). An then, I'm using a 500 MHz Celeron machine.

On Steve's point: I believe the whole EA community has high expectations on your project, now in the alfa stage. One question (and it sounds dumb for someone who follows UML developments as I do): Is RUP proprietary? If so, how are we going to handle this?

Jaime

[Steve_Straley]

Jamie,

After hearing the gyrations that you go through to build UC documents, I'm a bit dizzy! <lol>.   There seems to be alot of potential gaps in doing that especially in the area of ensuring that the latest UC information has been generated, read, cut, and then pasted into the correct version of the actual UC document.   This just goes to reasure me that I'm not spinning my wheels trying to get EA-ReqPro out ASAP.   But there are alot of other things that a "tool" can (or can not) do that cutting-and-pasting can, but is too timely to do so.  For example, one short coming of RequistePro is the ability to actually LINK external documents to a RUP document, and I don't mean through WORD, which is yet another problem with RequistePro.   This is why I'm spending alot of time on trying to design a Template Designer and then a Document Designer.

On to your last point, RUP as a PRODUCT is "registered" as a product or, to quote Rational, it is "best practices is a web-enabled set of software engineering processes that provide you with guidance to streamline your team's development activities.".   However, following the RUP paradigm is NOT protected and the generated format of the documents is NOT protected.   The USE CASE document, having a header, a footer, a TOC, an Overview, a basic flow, an alternative flow, sub-flows, pre and post conditions, and external items is no more copy protected than... the word "Windows".   Most companies, and GE included, follow the templates, follow what the "tools" (Rose, Requisite Pro, ClearCase and ClearQuest, Purify, et cetera) provide.   And in some cases, including GE, they've modified the RUP process to tie in with their own overall process, in this case Six Sigam... but it can also apply to CPP and others.    

So, EA-ReqPro is a tool to generate RUP-based process documents and is NOT a RUP plug in.   Does that help?

Steve

[Dennis Todd]

I'm going to put in my two cents here.

I don't use the RUP-(whatever!) I use HTML signicantly because everyone I know uses the web. I view the folders as document headers.

I build a folder structure that looks like, for instance, a design document. Maybe this was obvious to all of you, but once I saw that structure it was easy for me to relate to building what i needed in EA. One other key to producing HTML was dragging and dropping a diagram "anywhere", which now becomes a hyperlink pointer from Diagram A to Diagram B. So I don't even use the hyperlink connector anymore, the diagrams can point at each other.

No, RTF doesn't support it, unless it has been added to 3.5.

The web for our team is really easy, I can update a complete set of documents in a few minutes on webpage that is laid out to look like the design document.

Look at Geoff's EAExample, he uses it a lot and I take advantage of the fact I can create all of these links all over the place in HTML and tie things together.

Just some food for thought!

Regards,

Dennis

[Steve_Straley]

Dennis,

RUP and HTML are two different things.   Glad EA-as-is works for you and addresses your needs!

Cheers,

Steve

[PhilR]

Hi all,

Just want to clear up the "is RUP proprietary?" issue.

RUP is based on the Unified Process (UP) which was described in a book by the "Three Amigos".  If you describe an idea in a book it places it in the public domain (the actual layout and text of the book is copyright of course).

Amazon has the book at
http://www.amazon.com/exec/obidos/tg/detail/-/0201571692/qid=1036633414/sr=8-1/r
ef=sr_8_1/104-7519513-8356719?v=glance&s=books&n=507846

Alternatively you can download an excellent article on the UP at
http://home.earthlink.net/~salhir/UnderstandingTheUP.PDF

The UP book does not describe activities such as Configuration Management or Quality assurance - the manner in which these are integrated into RUP along with all sorts of articles, check lists and templates is what makes RUP proprietary.

However, I can take the Amigos' book and quite legally create a PUP (Phil's Unified Process).  Because Rational's lawyers are bigger than mine they may well object to the name etc etc but basically I have done nothing wrong.

The notation used by RUP is described in the OMG standard for Software Process Engineering Metamodel (SPEM).  This is an open standard available at
http://www.omg.org/cgi-bin/doc?ptc/2002-05-04

What this means for organisations is that they can create their own methodology based on the UP and using the same notation as RUP without infringing any licences.

For guidance on the bits that are missing in UP try the ISO 12207 standard.  A good overview exists at
http://www.abelia.com/docs/12207cpt.pdf

or the OPEN process framework at
http://www.donald-firesmith.com

[Steve_Straley]

Phil,

Thanks for the articulate clarification!   I know I don't want to call this EAUP <lol>...

Steve

[mwra]

The EAUP plug-in sounds an interesting development, especially if it aids links out to other documents - our UCs are exhaustively cross-referred to 2 other models and some of the customer's requirements documentation.

Although by turning our UC docs from Word to HTML the UC can be linked out to from within the EA HTML documentation the document links are not relative - unlike the rest of the EA links.  It would be useful if there were an option to have linked documents as relative references (or perhaps using a common document root ref'd in a .JS file).

Such an option would give a very portable 'view' for those who are consumers of EA data rather than authors.  No-techie 'consumers' can view the information in a tool they understand (web browser) and can't 'break' the original data.  At worst the they corrupt the HTML which can easily be re-run.

Regards

Mark A

[Steve_Straley]

Mark,

From our perspective, we're not looking at this as a plug-in; rather, a suite that competes collectively with Rose.   Having the complete set would, in our opinion, ease the seemingly up-hill battle with the corporate types that compare EA exclusively against the entire Rational suite.   It's unfair but what we're facing and we're tired of it.

One of the problems, for example, with RequistePro is they handle external documents by letting Word handle it.   Talk about passing the buck!   So we've taking a different approach and want to expand on this once EA-ReqPro is released.   Folders are the key things that distinguish what type of document is to be generated.  They also distinguish what type of items or requirements can be added to them.  In that, we've added the option to attach outside external documents to them.

Now, in the Template Builder and the Document Builder, you can add the external files anywhere in the document.   We also hope at some point to link folder to folder; that way, for example, you can link a Stakeholder Document to a Deployment Document to a series of Use Case Documents.  So with this flexibility I think you should be able to get the "linked documents as relative references".  Currently, our initial plan is only to generate the HTML pages and links but if there is alot of groaning, we may turn to RTF <grrr>...

FWIW, we just finished the CROSS-REFERENCE report which checks to see unresolved TO and FROM requirements items and generates a report.   This report can be automatically dumped into a new feature called TO DO.   The idea of TO DO's is to allow people to dump not-quite-ready requirements into a central spot that can be then turned into actual requirements.   Also, we're putting the finishing touches to the Template Builder / Document Builder so we can not just see input, but output as well.   We've also started writing the user manual that should be available for download soon (you can see the screen shots of the program as well).

HTH,

Steve

[mwra]

Steve,

Sorry, I stand corrected - not a plug-in!  Notwithstanding, it still sounds interesting, especially with the extra info you've just supplied.

RTF vs HTML.  For my 2p-worth I see HTML as an intermediate format for sharing disemination whereas a more formal format (DOC, RTF, PDF) will be needed for final deliverables - this is likely to be driven by the customer dictat rather than what the EA project user might wish to provide.

Regards

Mark A