Re: [papyrus-rt-dev] Updating and maintaining "A UML-RT Profile for Papy

[Peter Cigéhn <peter.cigehn@xxxxxxxxx>]

Hi,

If I remember correctly it was mainly the figures, like Figure 2, that had issues when converted to Google Document format. It could have been some issues with track changes as well, i.e. when imported and the original Word Document had tracked changes on, then the Google Document had a lot of "changed" text which made the Google Document version hard to read.

Regarding the figures and drawing them in Papyrus instead, I would say most of them already are, e.g. all the diagrams showing the stereotypes and related constraints are from the profile model itself. I think that the main issue are with figures/pictures that are not really possible to draw in Papyrus as a formal "model", e.g. the visualization of state-machine refinements in figure 2. But Bran is probably the one the has the best insight into the issues we saw, and the reasoning around the decision of maintaining the profile document on Word format. And also why some figures have not already been made in Papyrus.

/Peter Cigéhn

On 3 March 2017 at 15:15, charles+zeligsoft.com <charles@xxxxxxxxxxxxx> wrote:

In two bugs, (Bugs 507968 and 513036), Peter has indicated the following issues:

Bug 507968:

We have had some severe issues with a Google Document version of

this document to lose lots of information in certain figures (check for

example Figure 2 and Figure 3 in the Google Document version and you will

see that they have lost their text/labels). Bran decided to revert back to

maintaining the profile document in the original Word Document format. I

suggest that we if/when the proposed changes actually are to be included,

that this is made in the original Word document.

 Bug 513036:

But due to format issues with this document on Google Document format, it is highly recommended that the UML-RT profile document is further maintained/updated on its original Word Document format.

Are there other issues apart from the diagrams issue listed in Bug 507968?

That particular issue is caused by the inability of Google Doc to properly handle Visio “models.” For that particular case, I would contend that those images should really be created in Papyrus and imported as images into a document, regardless of the editing tool used.

An even better approach would be to \use something like GenDoc to automatically create the document (we would still need a Word or OpenDocument file for this) - but that’s a “Future” endeavor.

The advantages of the Google Drive are the capability of “real time” collaboration and the automatic creation of a limited number of versions. I would contend that we do not really need collaboration for a specification document.

However, retaining previous versions should be done. Currently, if you look at the Google drive folder there this particular document is stored, there is an “archive” folder to hold previous versions. File names are also annotated with he date and time of the last change. I would request that this be done for each update to the document so that we can retain history (it would be better if we could automate this…, but again “Future”). Note that I have used the same approach to versioning in many other folders in the Google Drive.

For now, my preference at this point would be to update the Word document, as Peter suggests, and ensuring that versioning is done as per the previous paragraph, so that we can maintain a history of the changes.

In the short/medium term, we must replace the Visio drawing with a Papyrus model - we have to use our own tools whenever possible.

In the medium/long term, we should be able to generate that documentation from models (e.g., using GenDoc).

Finally, we will need to officially “publish” these documents at some point in time. The questions are then ones of copyright and license, and of publishing format (Word, OpenDocument, wiki, etc.). By default, and as the author of the document as per its properties, the copyright for belongs to Bran (copied), so I need to discuss that with him.

Thoughts and comments are welcome.

Regards,

Charles Rivet
Senior Product Manager, Papyrus-RT product leader

charles@xxxxxxxxxxxxx

_______________________________________________
papyrus-rt-dev mailing list
papyrus-rt-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/papyrus-rt-dev