Generating documentation for UML Use Cases (XML,XSL,XSD example included)

Capturing Use Cases is not easy at all, the Use Case diagram items are scarce and simple for an obvious reason, to keep the diagram simple and understandable. Just make a quick search in Google images for 'use case diagram' to get an astounding amount of examples of how badly the theory has been understood by many...

Someone misunderstood basic theory here...


Every diagram should be accompanied by the corresponding documentation where every element has to be described and cross referenced.

I highly recommend using professional UML tools to generate diagrams, but as soon as you place documentation in them, you are linked to their brand, and even when xmi should allow easy export of project information, it seems not to. A workaround to this consists on using them to draw the diagrams and keeping the documentation, which becomes as valuable or more than the diagrams as it grows in size, in a separate easy-to-export-and-maintain format.

Keeping project documentation in XML is a good idea only if the corresponding XML is strongly typed and well defined in an XSD. To print the documentation  an XSL stylesheet is of great help.

Once these documents are defined, a general XML editing tool can be used to document use cases and link them to their diagrams in an easy and comfortable manner.

A free and useful tool is XML Notepad 2007, even being 7 years old now, it works nicely and makes working with XML easier. Sure there are good free and commercial alternatives for those who are in love with UNIX systems.


It can be downloaded from Download XML Notepad 2007 from Microsoft, hope they update it soon.

Given the XML file, it automatically uses the associated XSD and XSL to maintain its structure and provide a not-so-good visualization. For proper visualization I personally prefer using Firefox.

So here you have, a base template for capturing your requisites and publish the associated documentation, you may want to adjust the XSD and XSL to your specific needs.

Download the XML Schema Definition.
Download the XSL Stylesheet.
Download the example XML.

Hope you find them useful.

Comments

  1. EvanOctober 22, 2014 at 3:10 AM

    How about using a UML maker or a desktop or online application that supports xml for drawing uml diagrams. I saw a tutorial somewhere regarding this.

    ReplyDelete
    Replies
    1. Ramón David Talavera SuárezNovember 2, 2014 at 10:30 PM

      Sure, once the diagrams are generated they can be linked into their correspondig documentation easily.

      Delete

Post a Comment

Popular posts from this blog

Qt Signals and Slots, Connecting and Disconnecting

Image
Slots, slots everywhere... by Ramon Talavera Qt connects widgets by means of a nice designed scheme based on the idea that objectS may send signalS of different typeS to a single object instance: This is a screenshot of the example code running. The main application creates dialogs A and B and then connects the signal from A to the signal slot in B. I cannot believe I have clicked it 100 times to show you that it works... Declaring the signal:  A declares to be able to send signals of type ' somebodyClicked ': class ObjectADialog : public QDialog { Q_OBJECT public: explicit ObjectADialog(QWidget *parent = 0); ~ObjectADialog(); signals:      void somebodyClicked(QString who); protected: void closeEvent(QCloseEvent *event); private slots: void on_pushButton_clicked(); private: Ui::ObjectADialog *ui; }; Declaring the slot: B declares to contain a slot method for signals to connect to:   class ObjectBDialog : public QDialog
Read more

Vaadin 7: Detect Enter Key in a TextField

Vaadin 7: Detect Enter Key in a TextField This can be easily achieved just by adding a shortcutlistener whenever the TextField gets the focus and remove it when it blurs. From an IOC perspective wrapping the TextField would most probably result in less rework than extending the TextField: For example: TextField myTextField = new TextField("A text field"); myTextField.setImmediate(true); OnEnterKeyHandler onEnterHandler=new OnEnterKeyHandler(){             @Override             public void onEnterKeyPressed() {                  Notification.show("V oight Kampff Test ",                     Notification.Type.HUMANIZED_MESSAGE);             }         }; onEnterHandler.installOn(myTextField); ------------------------------------------------------------------- And the code for OnEnterKeyHandler is: import com.vaadin.event.FieldEvents; import com.vaadin.event.ShortcutAction; import com.vaadin.event.ShortcutListener; import com.vaadin.ui.TextField; p
Read more

JAVA JPA WITH HIBERNATE AND H2 Tutorial

Image
JAVA JPA WITH HIBERNATE AND H2 Tutorial Setting the environment: Download and install H2 Database http://www.h2database.com/html/download.html Create a connection to the database, in my case I am using Netbeans. Creation of a new Database Connection can be done from the Services Tab, Databases node: Have in mind that it is not possible to test the connection before the JDBC URL has been written into. Select the PUBLIC schema when asked. And put a name onto it, I decided to name it as "Hibernate 101 on H2" Download Hibernate http://sourceforge.net/projects/hibernate/files/hibernate3/ JPA with Hibernate: For the shake of portability and standarization we will be using JPA. Natively speaking, Hibernate relies onto a context configuration file -  hibernate.cfg -  and a single or many persistence configuration files  - hibernate.hbm.xml - .  On the other hand JPA configuration is based on just one file:  persistence.xml.  Netbeans offe
Read more