Useme was born as a requirements management tool to be used internally by the Etish consultants when dealing the hirsute issue of requirements management for their clients. The tool was designed to fulfill a set of needs that we perceived time and time again whilst helping our clients organise (or, in many cases, reorganise) their requirements in a rational and usable fashion. The tool has shown to be invaluable for us in enabling us to build strong and consistent requirements documentation, without the excessive expenditure in time and committment that is required when developing the requirements model either by hand or via the commonly available automated requirements management tools.
We have therefore decided to make Useme available to the worldwide software development community as an open source effort, in the hope it may benefit others at least as much as it has helped us.
This document is an introduction to Useme version 1.0. It describes its main features and it then goes into a more detailed explanation of the fundamental concepts on which Useme is built. You can also explore the reasons we had for building Useme in The rationale for Useme. For a rapid overview of the tool please refer to the Overview of Useme, or, for a high level visual inspection, consult Visual tour of Useme , which also contains screenshots of the user interface. The long term vision for future versions of Useme is much more complete than presented in this document; please refer to our Project Plan for details on future additions and improvements.
Useme is an open source collection of tools that together form an automated requirements management system. It draws advantage from a multi tier architecture, based on Java J2EE, which makes all tools in the Useme suite highly performant.
Useme is use cases driven and it merges the two concepts of UML model and document specification. Traditionally UML provides clear and specific rules on how to compose a use case model, but does not give any binding prescriptions on how the textual specification documents that express the behaviour of a use case should be put together. For this reason under normal practices a gap exists between the requirements model as defined in a UML tool and the actual textual specifications of the supporting documents. Typically the UML model defines use cases and actors as simple elements, possibly grouped into UML packages, and the structural relationships between these elements. The use case and actor specification documents are then separate, textual entities, which, after the initial effort of producing them to reflect the topography of the UML model and its connectivity, in most cases rapidly loose their association with the model due to the hard realities of a normal development process, where aggressive production schedules and constant change are the norm and where the developers are not afforded the luxury of manually maintaining the two types of artifacts (model and document specifications) in a consistent state at all times. Useme solves this problem by enforcing a well organised, structured definition of the documents in the first instance and by automatically updating all relationships between the documents when requirements evolution or change dictates it.
Useme utilises specialised, custom built form based editors with one type of editor for each supported type of requirements document. These editors capture the contents of a document in a highly structured fashion: the document's meaningful components are identified and handled by Useme as the document's building blocs in the appropriate editor form. Furthermore the editors enforce specific UML related rules when the document is being modified. In this way Useme makes sure that all document specifications are well formed and valid, that they correctly represent the underlying UML model, and that they are consistent with each other throughout the project, regardless of the number of analysts that are working on them.
Useme supports rich text, including text that may contain smart links. Smart links are the representation of relationships between the artifacts in the UML model when expressed within a textual context. Smart links may be of various natures, corresponding to the various stereotypes that characterise the model's relationships. This enables the Useme editor client tools to manage the interconnectivity between documents and document elements and to ensure the consistency between the UML facet and the descriptive or textual facet of the requirements model for a given software development project. All Useme editors and a few of its wizards are rich text “enabled”. Provided you are working in a component that is prepared to accept rich text, you can add a new smart link or remove or modify an existing one.
Useme supports the sharing of production and consumption of requirements documents among all the different stakeholders in a sofwtare development team. The requirements documents for a specific development effort is contained in a Useme project that is stored on a centralized server. The server is managed by a Useme Administrator, who is responsible for setting up the server, for creating and configuring each Useme project and for authorising specific users to work on the project as requirements analysts. These activities are managed via an administration tool. Useme editor clients installed on the analysts workstations enable them to perform their requirements specification work as a team. Useme ensures that the project remotely stored on the server is kept up to date with the analysts modifications and that, conversely, all analysts working on the same project are provided at all times with an up to date snapshot of the project. The collaborative nature of Useme is particularly attractive in a world in which remote contributions to one and the same project from different corners of the globe, be it a commercial or an open source endeavour, have become the norm rather than the exception.
An independent, web based publishing tool ensures that all artifacts that are deemed ready for viewing by the individual analysts are published for consumption among all the stakeholders of the development project. The publication process ensures that all special elements in the requirements documents, such as smart links, are rendered in the most appropriate fashion for the format in which the document is being produced. As an example, smart links are represented by HTML hyperlinks when the documents are published as HTML pages. Version 1.0 of Useme only supports publication in the HTML format, but pdf and other popular formats will be added in future releases. Publication is extremely timely, ensuring, if required, that any change that is applied to a document appears immediately in the published artifact.
The editor clients, as well as the administration tool, leverage the well known Eclipse platform: this makes the capture and subsequent management completely integrated in the overall software development process, easing communication between different team roles and ensuring that the requirement capture/implementation/test cycle is as transparent and as timely as possible. The clients are organised as modular Eclipse plugins (one for each type of supported requirements document) that can be independently contributed to the Eclipse platform, so that any given development team may add only those plugins that are of interest, thereby avoiding unnecessary bloat to the Eclipse platform itself.
A Useme server is the repository of all Useme projects. It is installed, configured and managed by a Useme Administrator, who is responsible for creating Useme projects on the server, for customising them and for assigning analysts to any given project, granting them access to and work privileges on that project.
The server is completely defined by its connection parameters, namely the name and port number of the machine on which it is installed. Each Useme analyst is provided with a username and password to access the server.
For any given development project, the server centralises all requirements related artifacts in one place. It then serves this information to two types of clients: the Eclipse based editor plugins and the Publisher. All team members collaborating to the production of requirements artifacts access the server from their remote Eclipse clients and contribute to the requirements definition. When documents are ready for publication, they are made available to all of the project's stakeholders by the Publisher, an intelligent engine that produces formatted documents for every interested party to peruse, comment on and/or utilise for the ensuing development. As already mentioned, the Publisher currently supports the production of HTML documents only, but other formats will be available in future releases.
The Useme Administrators are the only persons that may work with Useme servers, utilising the administration plugins. The Administrator has also the power to decommision any given Useme server, to remove or rename projects and to withdraw access permissions to any analyst that was previously assigned to the project.
An analyst that wants to work on a project in one or more of the editor clients needs to define a connecting route to the server, as well as her login parameters, once and only once. We call this process “adding a server location”, which means that all information pertaining to the connection to the server is provided by the analyst and stored on her local machine. All subsequent connection and user authentication across various sessions of work happen behind the scenes, without disturbing the user's activities.
Once the analyst has added the location of a specific Useme server, its contents are made available to her in her editor clients.
The representation of Useme servers on the Eclipse editor clients is refreshed automatically and on a (frequent) periodic basis to ensure that the analyst has an up to date view of each server. Section The team synchronisation challenge explains the synchronisation processes in greated detail.
A Useme project is a container for all documents defining the requirements for a given software development project. A Useme project is not meant to contain anything other than requirements related documents. Different types of documents are supported, and the list will continue to grow in future releases.
Useme projects are stored on a centralised Useme server and shared among all analysts working on the development team to define requirements.
All tasks that pertain to the management of the project's lifecycle, namely creation, renaming, deletion, as well as management of authorisation of specific workers that are enabled to contribute to the project, are the responsibility of the Useme Administrator, who utilises a specific Eclipse based administration plugin for this task. Analysts only have to worry about project content.
Modification to a project's content is performed, via the Eclipse based Useme editor plugins, by those analysts on the team that have been granted access to it. In order to work on a project, an analyst must first subscribe to it. The act of subscribing allows the server to know which users are working on which project at any given time and makes the current contents of the project fully available to the user in her client tool. The analyst needs only subscribe once. The project will be available to her throughout all her future sessions with the editor clients. The analyst may also unsubscribe from a project any time she wishes to.
When the Administrator creates a new project, this is not just an empty shell, as it is provided with a basic organizational structure that is common to all Useme projects. A Useme project is composed of folders, UML packages and requirements documents.
Folders are simple containers that group the different types of requirements documents, facilitating their classification in a similar way to a directory on a filesystem. For instance, all use case documents will reside in folder “Use Cases”, which is provided by default. In version 1.0 all top level folders are provided as is and cannot be modified or deleted by the analyst. Future versions will enable the creation and modification of top level folders.
UML packages are folders that may contain either actor specification or use case specification documents, just like their UML counterparts, hence their name. These are fully controlled by the analyst, who may create, delete or modify them. Besides its name and its location in the project tree, a UML package has an associated optional description to clarify its purpose and its uses.
The heart of a Useme project is undoubtedly provided by the Useme documents, which are collected in folders, or, for specific types of documents, in UML packages. They are fully controlled by the analyst, who may create, modify or delete them. They are described in the next section, Structured requirements documents.
Useme guides the Analyst by controlling the location in which UML packages or specific types of documents are created. For instance, you will not be allowed to create a use case specification document within the Glossaries folder.
The representation of a Useme project on the Eclipse editor clients is refreshed automatically and on a (frequent) periodic basis to ensure that the analyst has an up to date view of the project, with all the modifications that have been recently applied by other analysts on the team. Section The team synchronisation challenge explains the synchronisation processes in greated detail.
When the Publisher is utilised, the entire Useme project is made available to the project stakeholders, who may navigate through the available artifacts at will.
The importance of sound, well structured documents has long been recognised in many authoring realms. When documents are structured, content can be controlled and validated in a more straightforward way. Furthermore reuse and refactoring of content are easier and more natural activities. Structured documents also facilitate information sharing because all documents of a certain type have the same look and feel and the same internal organisation across a project.
Since one of our primary intentions when designing Useme was being able to reproduce the UML model at the level of the textual content, the decision of organising the requirements documents in a structured fashion was quite obvious and natural.
Useme documents have a well defined organisation, which is based on XML and underlined by a specific XML schema (one per type of document). We created the XML schema from an analysis of each type of document, by identifying the elements that are characteristic of that type and by using these as the building blocs of our documents. The schema incorporates the existing UML rules as well as best practices that have been repeatedly suggested by many requirements capture experts but never enforced.
In a way, the XML backbone of the Useme documents can be viewed as our standard for the design and development of requirements content. This, we believe, is one of the great strenghts of Useme. Many times we have heard developers expressing the opinion that requirements documents are too “fuzzy” and insufficiently structured to be usable beyond a very initial stage of development. This is true insofar as there are no capture and management tools that empower the user to define the requirements in a more exact fashion, without wasting too much of her precious time doing it and without loosing the quality of communicability of the documents to the end users, which is a fundamental need of modern requirements documents.
The availability of structured requirements documents also opens up a realm of possibilities in terms of tasks other than content creation that may be performed by the automated requirements managements tool in a relatively straightforward manner. For instance, sophisticated interrogation and or reporting on the documents composing the model can be performed via detailed searches that are based upon the documents internal elements. Automatic test analysis of a use case and automated initial definition of scenarios and test cases are also examples of tasks that are currently extremely time consuming as they are typically performed manually and that may become much more approachable with Useme. Both these examples represent features that are not yet available in Useme, but that we intend to provide in future releases.
As an example, let us consider a use case specification document. Elements characterising the document go from the simple “Description” or “Purpose” to rather complex elements such as the “Main flow of events”. This in turn contains and is defined by sequences of other simpler elements such as “Event” or, within the “Event” element, a number of “Step” elements. However, the last “Event” element can only contain one “Step” element, namely the one identifying the end of the use case. The analyst needs not worry about this inherent complexity, as the use case editor tool (as indeed all Useme editor tools) transforms the XML structure and its rules into an intuitive and easy to use form based editor, which guides in the document compilation, warns against incompletenesses in the specification and forbids errors that would invalidate the document with respect to either the UML rules or the underlying XML schema.
Useme documents may contain information on use case relationships as expressed in the UML model, as described in section Relationships below.
One of the salient and most novel features of Useme's documents is the fact that they may also contain rich text, namely text in which the analyst can define smart links. These are the representation of document relationships at the textual level. Once created by the analyst, these links are automatically kept up to date by Useme throughout all changes of the requirements model, whilst Useme also ensures that no links are broken at any time. Smart links are the subject of section Smart links below.
Finally, it is to be noted that Useme is meant to support in the definition of requirements documents in all phases of documents evolution. Despite the structured nature of the documents, the analyst is not forced to immediately define a document in all its details. The initial document may be as bare bones and sketchy as required by the user interviews and capture process. For example, in the case of a use case specification document the analyst may intuitively know that a use case needs to include another use case that exists in the model, but without yet having developed the main flow of events and therefore without knowing where exactly in the flow the inclusion will take place. Useme enables the analyst to define the inclusion relationship without producing an error and forcing the analyst to provide the missing information, but simply flagging the relationship with a warning that it has not been explicitly declared in any steps of a flow of events. However when, later on in the development process, the document is ready for refinement and completion, the analyst is made aware of this incompleteness in the document by that same warning flag. Useme is there to support the analyst in achieving the goal of writing a correct, valid, understandable and unambiguous document.
The number of requirements documents that are supported by Useme will increase with later releases.
One of the most meaningful features of any requirements model is its connectivity. Elements are associated with each other via relationships, each of which is characterized by the two elements that participate in the association, as well as by the association's nature, or stereotype.
Whilst this is easily shown in a UML model, all practitioners know that it is difficult to correctly define relationships in a textual document. Frequently we find, for instance, extension being used but no extension points being declared. This is not just a “purist” matter, the implementation of the system depends on the correctness and completeness of this information. Useme eliminates all these syntactical problems by using editors that guide through the correct definition of relationships, preventing the analyst from doing anything invalid, and that warn her when something is incompletely specified.
Furthermore the frustrating experience of seeing relationships mentioned in a document but difficult to follow in practice because this requires digging into the documentation to find the relevant linked documents is eliminated by Useme, which provides automatic navigation between related documents. This is a great facilitator and time saver.
In Useme we define the two participating elements as the provider and the consumer of the relationship respectively. Which element is the provider and which one is the consumer is dependent upon the stereotype. For instance, in an "include" relationship between use cases, the base use case is the consumer and the included use case is the provider. In a "weak dependency" relationship between two documents or document elements (which provides a generic reference from one element to the other), the document that contains the reference is the consumer and the referred document is the provider.
Once the analyst defines these relationships, Useme manages them through the project's lifetime: it constantly ensures that each relationship is syntactically correct and meaningful in the context in which it was created and that the connectivity expressed by it is maintained at all times and not accidentally destroyed by, for instance, the removal from the project of one of the two elements participating in the relationship. Any change in the representation of the association's members, such as a change in the name of one of the two participant elements, is also automatically tracked and reflected in the association.
Given the modular nature of Useme, in which each plugin contributes all the functionality that is necessary to manage a specific type of requirements document, the plugin also defines the stereotypes that are supported by that document type and contributes those stereotypes to make them available to the analyst as soon as the plugin is installed and activated.
Useme has a number of different ways in which relationships can be defined and managed, depending upon the particular stereotype that is required. In general however the relationship is first defined from its consumer element. The provider document does not need to be opened (or indeed it can currently be opened by a different user) in order to define, alter or remove the relationship. This makes the tool very dynamic in its usability in a team context.
Similarly, no element may be removed from the requirements model if it is the provider of at least one relationship. This ensures that no documents will contain any “dangling”, or unsatisfied, relationships.
All this is actually much less confusing than it sounds, as Useme provides all the necessary guidance and help to ensure that relationships are managed correctly.
Once established, these relationships are generally rendered in the participating requirements documents as textual smart links, which enable the viewing users to seamlessly navigate from one element of the association to the other.
For many internal document components, Useme expresses descriptive content as text that can contain active references to other documents or document elements. This is what we refer to as rich text. The active references within the rich text are smart links, also referred to as hyperlinks, which represent document relationships as expressed in a textual context. As already mentioned, smart links are one of the most innovative features of Useme, as they allow the analyst to fully establish the connectivity of the requirements model once and to let Useme manage it for the life time of the model, through the inevitable evolution of requirements and, most importantly, through the ongoing challenge of requirements change.
All Useme editors and a few of its wizards are rich text “enabled”. Smart links are defined in the text as special regions that are blocks of text that are “atomic”, i.e. they only make sense when they are complete. Therefore these regions are to be handled as a unit and no editing can occur inside of them. When smart links are selected to modify or delete the links, the operation can only occur on the link in its entirety (and via a special Hyperlink wizard). Therefore the behaviour of the selection mechanism or of the cursor over a link region differs from the normal expected behaviour. For example, if you select a portion of a smart link, the selection expands to cover the entire link; if you try and enter a link region with the cursor, the caret position jumps to the opposite extreme of the link region, to indicate that this is a read only area.
When deleting a smart link, if any ancillary special handling is required, due to the nature of the removed link, Useme processes this automatically. An example of this situation is the case in which you delete text in a step of a use case's flow of events and this text contains a “use subflow” hyperlink. In this situation Useme not only removes the link itself, but it also ensures that the subflow being referred to in the smart link is unlinked from the step, namely that the appropriate existing origin point in the subflow's Origin Points table is removed as well.
When documents are being published, Useme's Publisher intelligently parses all documents for smart links and converts them to a format that is appropriate for automatic navigability. For example, HTML documents display the smart links as classic HTML hyperlinks, which can be used to explore the model's connectivity in an easy, quick and straightforward fashion.
The collaborative nature of Useme opens the door to a number of issues around the appropriate strategy to be adopted in order to keep all users that are simultaneously modifying a requirements model for a software project in synchronisation with each other. One choice would be to rely on the user to explicitly request a project refresh when desired. This approach is fraught with peril, as the burden of maintaining information up to date cannot be placed on the user's shoulders exclusively. At the opposite extreme, we could be ultra cautious and force a refresh of the user's view of the project as soon as any change occurs on it at the server level. This would also be a recipe for disaster as multiple modifications to the project would end up enormously slowing down and ultimately crippling the system, not to mention constantly interrupting the user's flow of work.
Our approach relies on two different mechanisms.
First of all, the project is automatically and silently refreshed every time the user requests an action the requires a communication with the remote server. In this way we are ensured of timely synchronisation when the user requires it and in a fashion that is not disturbing to the user's work because the refresh hitchhikes the communication with the server that would have had to happen in all cases to satisfy the user's request. In some situations it may occur that the refresh to the project invalidates the user's request. For instance, a user may request to open a document which may have been deleted by another team member in the time intervening between the last refresh and the user's deletion request. In such cases Useme informs the user with an appropriate message and aborts the delete action.
The second mechanism is a periodic refresh of all projects the user is subscribed to, that happens silently and behind the scenes between user requests. The frequency of the refresh depends on the user interface context; for example, when the editor client is displaying the main workbench, periodic refreshes will occur less frequently than when the client is displaying a wizard.
Useme is still very young. Our vision for it goes well beyond version 1.0. Please refer to our Project Plan for an indication of the future directions we would like Useme to take. Please note however that the plan is work in progress: future features will be prioritised and assigned at a later date, depending, in large part, on the desires and needs of the Useme community.
In this paper we have presented a description of both the high level features of Useme and some of the basic concepts behind it. We have gone into some detail in the description of the fundamental concepts and mechanisms in the hope that you gain an understanding of and an appreciation for the usefulness of the tool in capturing and managing requirements, one of the most complex, error prone and, as many surveys have determined, costly arenas of software development.