Author Topic: Document Generation  (Read 23119 times)

nick.hynes

  • EA Novice
  • *
  • Posts: 7
  • Karma: +0/-0
  • I love YaBB 1G - SP1!
    • View Profile
Document Generation
« on: September 18, 2006, 02:08:02 pm »
This remains the #1 issue for our organisation.

The architects are very happy with EA; however getting buy-in from the BA teams and channel managers is impeeded because of the issues surrounding document generation.

The issues for us are:
  • The need to create different heading levels for nested packages. Our projects often include many different levels of abstraction. We indicate the level of abstraction by nesting packages at different levels, however the generated document shows all packages at the same level.
  • The need for rich text editing in the element descriptions panel. Our BAs need a WYSIWYG editor for package and element descriptions.


These two features would vastly improve our ability to deliver quality documentation to our outsourcers and integration partners.

We have read the related threads, and none of the solutions to date solve these specific problems.

Note: this issue has been reposted from a thread titled 'New RTF Generator...' because that thread seems to have died without a response.


Nicholas Hynes
Solution Architect
IAG (NZ)

thomaskilian

  • Guest
Re: Document Generation
« Reply #1 on: September 19, 2006, 07:02:36 am »
The RTF thingy has been requested for years. You will likely have to wait for 7.0 or so....

«Midnight»

  • EA Guru
  • *****
  • Posts: 5651
  • Karma: +0/-0
  • That nice Mister Grey
    • View Profile
Re: Document Generation
« Reply #2 on: September 19, 2006, 10:33:20 am »
Nick,

Some time ago - before EA had a WYSIWYG rtf feature - I ran up against the same kind of brick wall. After much pulling of hair and gnashing of teeth (and not a few dead ends with 'hand built' rtf files) I decided to build an automation tool that would handle documentation for me.

End result was a fair amount of work, but greatly improved documentation. Given what I now know about EA I realize the results could have been more favourable both ways.

Perhaps if this is important enough in your shop, and if you are going to reuse the capability a few times, it would be worth taking the time to build yourself a tool to take care of this. I know that does not solve your immediate problem, but the long run payoff might be sufficient to cover the inconvenience.

David
No, you can't have it!

Ozzone

  • EA Novice
  • *
  • Posts: 14
  • Karma: +0/-0
    • View Profile
Re: Document Generation
« Reply #3 on: October 03, 2006, 06:06:07 am »
I myself managed to produce quickly and easily rtf documents with the old generator. I run into many problems with the new one.

I have the same problems as stated here (heading levels) and some strange behaviour which my come from my not understanding the way the new template editor/generator works.

Can anybody help ond the heading levels and more generally in generating a nice report !

Jan ´Bary´ Glas

  • EA User
  • **
  • Posts: 408
  • Karma: +0/-0
  • Bary
    • View Profile
Re: Document Generation
« Reply #4 on: October 03, 2006, 06:14:28 am »
It is not working in hand made templates.
« Last Edit: October 03, 2006, 09:32:33 am by Bary »
Jan 'Bary' Glas

nick.hynes

  • EA Novice
  • *
  • Posts: 7
  • Karma: +0/-0
  • I love YaBB 1G - SP1!
    • View Profile
Re: Document Generation
« Reply #5 on: October 04, 2006, 07:02:21 pm »
A further issue I've just discovered, is that the it is nearly impossible to reformat documents in Word.

If you open a generated RTF document in Word, and attempt to modify the heading styles, you will notice that there are a lot of inter-dependencies between the various heading styles. The complex of the way styles are defined, coupled with bugs in Word make it impossible to reformat documents.

I've found it is easier to 'paste as text' into a new Word document, and apply formatting to the new document. I'm not asking Sparx to fix Word, but you do need to be aware that this is how most people are currently using your product, and the bugs in Word exacerbate the issues your users have with EA.

This appears to be low hanging fruit in my eyes, and I'm surprised this isn't higher priority for Sparx. If you could re-write the document generation module you would experience significant uptake from your EXISTING CUSTOMER BASE.

sargasso

  • EA Practitioner
  • ***
  • Posts: 1406
  • Karma: +1/-2
  • 10 COMFROM 30; 20 HALT; 30 ONSUB(50,90,10)
    • View Profile
Re: Document Generation
« Reply #6 on: October 04, 2006, 08:04:19 pm »
Nick,

IME the problem is not within the rtf generated by EA - it lies in the fact that rtf is not a Standard.  The rtf output is perfectly manipulatable in Word 97 but not in Word 2003 - Word 2003 manipulateable rtf is not useable in any prior version of Word.

As you say, the best (only) way is to paste the text into a formattable Word doc in the version of your choice.

MS have structurally changed the rtf spec so many times its ridiculous.  I think (IMO) the only tags left useable are bold and underline, let alone heading styles.



bruce
"It is not so expressed, but what of that?
'Twere good you do so much for charity."

Oh I forgot, we aren't doing him are we.

Ozzone

  • EA Novice
  • *
  • Posts: 14
  • Karma: +0/-0
    • View Profile
Re: Document Generation
« Reply #7 on: October 05, 2006, 12:46:16 am »
Well, well, complying about rtf and word does not really help us right now.

My problem is still that it worked fine (that is I could produce a nice document in a few clicks) with the old generator in EA 5 and cannot anymore...

For the future, we could advise EA to produce Opendoc format http://en.wikipedia.org/wiki/OpenDoc and hope future versions of word will be able to read it.

Ozzone

  • EA Novice
  • *
  • Posts: 14
  • Karma: +0/-0
    • View Profile
Re: Document Generation
« Reply #8 on: October 05, 2006, 12:57:56 am »
Ooops !

I should have proofread my entry. As stated on the page I mentioned

"the unrelated OpenDocument file format (formally known as the OASIS Open Document Format for Office Applications and usually abbreviated ODF) is sometimes mistakenly abbreviated to "OpenDoc", but this is an informal and coincidental abbreviation."

I meant OpenDocument file format of course !


Paolo F Cantoni

  • EA Guru
  • *****
  • Posts: 8595
  • Karma: +256/-129
  • Inconsistently correct systems DON'T EXIST!
    • View Profile
Re: Document Generation
« Reply #9 on: October 05, 2006, 01:08:30 am »
Since Sparx is a primarily a Microsoft shop, I'd think they'd veer more towards:
Microsoft Office Open XML

(see also:Comparison of OpenDocument and Microsoft Office Open XML formats)

Paolo
Inconsistently correct systems DON'T EXIST!
... Therefore, aim for consistency; in the expectation of achieving correctness....
-Semantica-
Helsinki Principle Rules!

«Midnight»

  • EA Guru
  • *****
  • Posts: 5651
  • Karma: +0/-0
  • That nice Mister Grey
    • View Profile
Re: Document Generation
« Reply #10 on: October 05, 2006, 04:11:52 am »
MS has contributed considerable resources towards an open source project to build a converter between the two XML dialects. I don't remember the name of the project, but you can find it on SourceForge with some searching.
No, you can't have it!

Ozzone

  • EA Novice
  • *
  • Posts: 14
  • Karma: +0/-0
    • View Profile
Re: Document Generation
« Reply #11 on: October 05, 2006, 07:33:16 am »
Awaiting for a standard in word processing documents we will have to work with the current RTF generator.

It just took me 15 mins to generate and reformat a 40 pages requirement document. What I had to do is

- rebuild the desired paragraph styles and levels
- renumber the pictures

I did not have to do that in the prior version. Does anybody know better ?

peter.zrnko

  • EA User
  • **
  • Posts: 253
  • Karma: +0/-0
    • View Profile
Re: Document Generation
« Reply #12 on: October 06, 2006, 01:47:10 pm »
Quote
It is not working in hand made templates.


I has to say, it's true. I've created a template, test it with on a small package with one element, it seems to be OK. Whe I run it on a big package it simply stop working somewhere in the middle without warning.

Is this realy so bad?
Peter

nick.hynes

  • EA Novice
  • *
  • Posts: 7
  • Karma: +0/-0
  • I love YaBB 1G - SP1!
    • View Profile
Re: Document Generation
« Reply #13 on: October 08, 2006, 12:30:11 pm »
Quote
Is this realy so bad?


In my opinion, 'yes'.

It depends where Sparx is positioning themselves in the market. I see them as serving... Enterprise Architects, who are responsible for large, corporate architectures. If so, then they need to be able to support large 'projects'. And the users (i.e. architects) need to be able to generate documentation for our partner companies, project teams and our line managers. Each of these groups expects professional quality documents, which can be quickly skimmed for detail or read and easily comprehended as a whole.

Currently, in order to produce documentation of that quality EA's users are required to perform time consuming, expensive and tedious manual work-arounds for what could simply be an automated process. This process is costly and can lead to the sorts of errors which leaves the user looking less than excellent in the eyes of their colleagues, managers and business partners.

So again, in my opinion this is a big issue, which could be easily fixed.

peter.zrnko

  • EA User
  • **
  • Posts: 253
  • Karma: +0/-0
    • View Profile
Re: Document Generation
« Reply #14 on: October 08, 2006, 10:24:52 pm »
Quote

I've created a template, test it with on a small package with one element, it seems to be OK. Whe I run it on a big package it simply stop working somewhere in the middle without warning.
 


The problem was with a template where Atttribute section was just behind other field and exported class has no attributes. I've solved it by placing one empty line before attribute section:

Package:{Element.ParentPackage}

attribute >


I've reported this as a bug.
Peter