QSOS Tutorial

License

Copyright © 2013 Atos.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Documentation License, Version 1.2 published by the Free Software Foundation. A copy of the license is available on this page http://www.gnu.org/copyleft/fdl.html.

History of modifications

Version Date Authors Comments
2.0 2013-02-13 Raphaël Semeteys Design and first draft.
2.0 2013-04-23 Thomas Moreau Translation into English

Introduction

The purpose of this tutorial is to guide you through the QSOS method by using the tools provided by the community project. So, this tutorial contains a set of use cases you might encounter. These use cases might not come up in the same order they are listed here. You can then use this tutorial either as a complete scenario, or as a list to be consulted when needed.

Managing templates

Overview of the templates

A template defines the structure or the grid of analysis of a QSOS evaluation. It contains criteria distributed as a tree on several sections.

The sections titled Maturity and Metadata are imposed by the QSOS method.

Maturity imposed in templates

Maturity imposed in templates

The Maturity section is an organized set of criteria unconditionally used to evaluate the maturity of a piece of software and the project in charge of its development, no matter what is the software or type of software. For more details on the criteria belonging to the Maturity section, read the QSOS method itself. Therefore, even if you modify this section in your template, these modifications will be overwritten to guarantee its compliance within the method.

The Metadata section is described further in chapter Modifying the Metadata section.

It is reserved to the management of a set of information peculiar to the template itself (metadata), such as the authors, its version, its date of creation, its date of last modification or its language.

Creating a new template

Installing FreeMind

The free software FreeMind is used to create and modify the template as mindmaps. It’s a software written in Java so it can be used on many platforms. Please read the official documentation1 for more details on the installation of FreeMind.

Be careful though, the minimum version required by QSOS is 0.9.0.

Getting the blank template

To create a new template, you need absolutely to start from the blank template in your language.

These blank templates respect the following naming convention: template_[language].mm. The English blank template is then template_en.mm.

The blank templates are available on the official website of the QSOS project at this address : http://backend.qsos.org.

Adding evaluation sections

Once the blank template is downloaded, open the .mm document with FreeMind. You’ll find the two sections imposed by QSOS : Maturity and Metadata.

To add new sections to your template, you just need to add and organize new nodes, while respecting the following formalism :

  • an intermediate node allows to organize your criteria. In addition to the title, you can write a description with a sub-node in the bubble format.
Bubble format to describe a node

Bubble format to describe a node

  • a final node (a leaf), is an evaluation criterion. It must respect the following conventions :

    1. the description of the criteria must also be in the bubble format ;

    2. the description of the score 0, 1 and 2 must be marked with the appropriate icons.

Criteria description

Criteria description

You’re free to create and organize the criteria of an evaluation that are peculiar to a type of software. The main node of your template must be the name of the type of software. This name is the unique identifier of the template.

Setting the name of the template

Setting the name of the template

Modifying the Metadata section

Metadata section imposed in templates

Metadata section imposed in templates

Please modify the Metadata of your template by entering the following information :

  • version : increase this value (according to the n.m rule) for each modification that must be applied on existing QSOS evaluations ;

  • language : language of your template (fr for French, en for English, etc.) ;

  • author : authors of the template, with their full name (name) and their email address (email) ;

  • creation : the date of creation of the template (with the YYYY-MM-DD format) ;

  • update : date of the last modification of the template.

Modifying the Maturity section

It is not possible to modify this section imposed by the QSOS method. Even if you modify the criteria in the blank template, these modifications will be overwritten.

Saving the template

The FreeMind file of your template is in .mm format. You can then save it and use it as you want.

Contributing the template

When you consider the template complete - at least for a first version, you can propose it to the QSOS community. To do that, go to this address : http://o3s.qsos.org/backend/app/connect.php.

Connection to O3S

Connection to O3S

An O3S account is needed. If you don’t have one, create one by clicking on Sign On.

Uploading a template on O3S

Uploading a template on O3S

From then on, your template can be used by the community to create new evaluations. Read the chapter Creating new evaluation.

The template is automatically stored in the Incoming repository of the QSOS reference. If it is considered as a good quality template, it will be approved by the community and moved in the Master repository.

To contribute to a new version of your template, repeat the process (don’t forget to increase the version in the Metadata section).

Modifying an existing template

The existing templates are stored in the QSOS community reference. They are grouped in two distinct Git repositories :

  • the Incoming repository : dedicated to the publication, the sharing and the use of evaluations and templates by the community. It is available to everyone via O3S. The only requirement is having an O3S account ;

  • the Master repository : dedicated to the storage of the evaluations and template that are considered good quality elements and are approved by the moderators of the QSOS community.

You can browse the two repositories on O3S2 and download the templates you want.

Browsing the templates reference

Browsing the templates reference

Once you have the template, use FreeMind to modify it. Read the chapter Creating a new template for more details on this topic.

Managing evaluations

Overview of the evaluations

A QSOS evaluation is based on a template of a given version, it inherits the structure and the description of the criteria from. It is a file in .qsos format that is manipulated via the XulEditor tool (see Installing XulEditor).

An evaluation based on a version of a template can be updated by another version of the same template, without loosing any existing data (see Applying a new version of a template).

Creating a new evaluation

Installing XulEditor

XulEditor can be installed in two ways :

  • as a Firefox extension ;

  • as a XulRunner standalone application.

While the first way is easier, the second has the advantage of allowing you to run several XulEditor instances.

Installing XulEditor as a Firefox extension

You just have to open the installation file3 in your Firefox browser4.

Once the extension is installed, it can be launched in the menu « Tools/QSOS Editor » of the Firefox browser.

Installing XulEditor as a standalone application

In order to use XulEditor as a standalone application, Mozilla Xulrunner must be installed.

Visit the official Mozilla website5 to install Xulrunner.

Then get the application archive6 and decompress it where you want.

The XulEditor can then be launched via the scripts xuleditor or xuleditor.bat depending on your operating system.

Using XulEditor

Files tab of XulEditor

Files tab of XulEditor

In the Files tab, you can create a new evaluation from a template coming from either your hard drive or from the QSOS reference. The second case is detailed hereafter.

In order to do that, click on the Remote template button and browse the QSOS templates reference.

Browsing the QSOS templates reference

Browsing the QSOS templates reference

You can filter the templates of the reference by the repository (Master or Incoming) and by language.

Once the template is selected, you can the start entering your evaluation by completing the fields of the different tabs.

The General tab contains information relating to the evaluated software (name, version, main license, etc.) and to the evaluation itself (template, authors).

General tab of XulEditor

General tab of XulEditor

You see that the name and the version of the template used for this evaluation are displayed but cannot be modified. For more details on how to update the template of an existing evaluation, read the chapter Applying a new version of a template.

The criteria tab allows you to browse in the tree of the criteria and to evaluate them :

  • by assigning a score between 0 and 2 depending on the meaning described by the authors of the template you use ;

  • by giving the reason and the source of the score.

Criteria tab of XulEditor

Criteria tab of XulEditor

Please give a reason of the score in the Comments field. It will make your evaluation more relevant, more useful and increases its chances to be approved by the QSOS community.

The Chart tab allows you to browse in the tree of criteria as a radar chart where you can click on the sections to see the sub-criteria or browse via the breadcrumbs.

Chart tab of XulEditor

Chart tab of XulEditor

The criteria colored in red are those that have not been evaluated yet. It allows you to quickly identify the missing parts to complete your evaluation.

Saving an evaluation

In the Files tab of XulEditor, you can save you evaluation on your hard drive (Save locally button) to possibly edit it later (Local evaluation).

Contributing an evaluation

When you consider your evaluation is complete - at least for a first version, you can then propose it to the QSOS community.

There are two ways to do it. The first is, like with templates, to connect to the QSOS backend7.

Uploading an evaluation to the QSOS reference

Uploading an evaluation to the QSOS reference

This requires an account on O3S. If you don’t have one, create one on the same website.

If you already have an O3S account, you can also save your evaluation directly on the QSOS reference with XulEditor, via the Save remotely in the Files tab.

Saving on the QSOS reference with XulEditor

Saving on the QSOS reference with XulEditor

Visible timeline of your contribution in O3S

Visible timeline of your contribution in O3S

From this point, your evaluation is visible by the community in the Incoming repository of the QSOS reference. If it is considered as complete and objective, it will be approved by the community and moved to the Master repository.

To contribute a new version of your evaluation, repeat the process.

Modifying an existing evaluation

XulEditor allows you to modify a QSOS evaluation coming either from your hard drive or the QSOS reference. The latter is described hereafter.

In the Files tab, click on the Remote evaluation. You can then browse in the QSOS reference by filtering the evaluations by the type of software, the repository (Master or Incoming) and the language.

Browsing the QSOS evaluations reference

Browsing the QSOS evaluations reference

Once the evaluation is selected, you can then manipulate it and modify it in XulEditor.

You cannot overwrite an evaluation that is not yours. The reference doesn’t allow this but it will tell you who contributed this evaluation. You can contact her then.

Evaluation Overwrite attempt

Evaluation Overwrite attempt

If you can’t contact this user or she hasn’t replied, contact one of the QSOS moderators who will arbitrate and unlock the situation. TODO : add the moderators’ mailing list.

Applying a new version of a template

XulEditor allows you to update the template used in an evaluation. It allows to inject developments brought into the template and also to ease the translation of the evaluation (by applying an already translated template).

To do that, you first have to open the evaluation that you want to update (Local evaluation button or Remote evaluation in the Files tab). Then select the new version of the template to apply, whether it’s coming from your hard drive (Local template button) or from the QSOS reference. This is the latter case that is described hereafter.

The Remote template allows you to browse the QSOS templates reference.

Browsing the QSOS templates reference

Browsing the QSOS templates reference

You can filter the templates of the reference by repository (Master or Incoming) and by language.

Error while applying a wrong type of template

Error while applying a wrong type of template

If you select a template that has a different type from the initial one’s, XulEditor prevent you to apply it and displays an error message.

Confirmation request if the template is in another language

Confirmation request if the template is in another language

If the new template is in a different language from the initial one’s, XulEditor requests a confirmation before modifying your evaluation.

Confirmation request of the modification

Confirmation request of the modification

And in every case, before modifying your evaluation, XulEditor requests a confirmation.

Please note that it is not forbidden to apply an older template.

Visualizing an evaluation in web mode

The O3S web application allows, among other things, to visualize the evaluation of the QSOS reference in web mode. This application provides many other features, linked to QSOS comparisons. Read the chapter Managing comparisons for a more detailed description of O3S.

Let’s consider that you have browsed 03S to the evaluation you want to visualize in web mode.

O3S Homepage

O3S Homepage

03S provides three evaluation visualization formats :

  • XML format (.qsos) ;

  • HTML format ;

  • FreeMind format (.mm).

Visualization in XML format

When you select this mode of visualization in 03S, and you have Firefox with the XulEditor extension, the evaluation is opened directly in the editor.

Visualization in XML format

Visualization in XML format

In every case, the XML file is also displayed by your browser.

Visualization in HTML format

When you select this mode of evaluation in O3S, the evaluation is displayed in your browser as an HTML page.

This page allows to fold and unfold branches of the tree of criteria to ease reading of the evaluation.

Visualization in FreeMind format

When you select this mode of visualization in O3S, the evaluation is displayed in your browser as a mindmap in FreeMind format (.mm).

Visualization in FreeMind format

Visualization in FreeMind format

This page allows you to take the following actions :

  • browse the evaluated criteria tree by clicking on the elements of the mindmap to fold/unfold ;

  • use the browsing menu to search by keyword or to move the visualization window (some evaluations can indeed be bigger than the windows’ frame when it’s fully unfolded) ;

  • use the displaying menu to adjust the size of the font, to adjust the size of the map and to change the background color ;

  • save the .mm file on your hard drive, by clicking on the title of the mindmap.

Although it’s a file in FreeMind format, please note that you do not visualize and do not save a QSOS template but a representation of an evaluation as a mindmap.

Please note that this type of visualization requires that your browser supports Flash.

Managing comparisons

The QSOS method was designed to compare different pieces of software of the same type, in order to make an informed decision. This comparison between evaluations from the same template take the context of the user into account thanks to a weighting system that can be used on the different criteria of the template.

The O3S web application allows to make weightings, comparisons and to export them into different formats.

Two versions of O3S are available, each is connected to one of the two repositories of the QSOS reference :

  • the official version8, connected to the Master repository ;

  • the sandbox version9, connected to the Incoming repository.

Creating a new comparison

Connect to the O3S instance you want. The list of the evaluations of the instance is displayed, filtered by language.

03S Home page

03S Home page

Select the domain you’re interested in. The list of the evaluations made with the version of the template you selected is displayed.

Comparison management page

Comparison management page

On this page you can take several actions :

  • visualize in your browser one of the listed evaluations in XML (.qsos)10, HTML or FreeMind formats ;

  • weight the template in order to customize your comparison ;

  • select the evaluations to be integrated in your comparison ;

  • visualize your comparison in web mode as an HTML table or an SVG chart ;

  • export your evaluation into OpenDocument format.

Weighting a comparison

The weight the template button displays a page allowing you to manage your weighting.

Comparison weighting management

Comparison weighting management

On this page you can :

  • enter the weights of each criterion of the template ;

  • save your weighting and associate it with the comparison ( Save button) ;

  • export/import your weighting into XML (.qw) so it can be reused. ( Export into XML and Browse… and Load) ;

  • and finally go back to the comparison management page ( Back button).

Visualizing a comparison in web mode

Visualization buttons in web mode

Visualization buttons in web mode

On your comparison management page, you can visualize it in your browser in several modes :

  • as a comparative table ;

  • as a radar chart ;

  • as a QSOS quadrant.

Visualizing a comparative table

The Online comparison button triggers the display of a comparative table of the evaluations that you have selected with your weighting.

Visualization as a comparative table

Visualization as a comparative table

This table is dynamic. It allows you to take the following actions :

  • show or hide the Comments columns of the different evaluations ;

  • adjust the size of the font used in display ;

  • toggle in radar charts visualization ;

  • go back to your comparison management page ( Back button).

Visualizing a dynamic radar chart

The Comparative chart button triggers the display of the comparison as a radar chart.

Visualization as a dynamic radar chart

Visualization as a dynamic radar chart

This chart is dynamic. It allows you to take the following actions :

  • browse the comparison in « Drill Down » mode : by clicking on the name of the criteria you want its sub-criteria to be displayed ;

  • browse the comparison in « Drill Back » mode: via the link back to upper level.

  • go back to your comparison management page (Back link).

Please note that this type of visualization requires that your browser respects the SVG standard.

You can save the SVG charts on your hard drive by using the save function of your browser.

Visualizing a QSOS quadrant

The O3S application allows to visualize your comparison as a QSOS quadrant.

Visualization as a QSOS quadrant

Visualization as a QSOS quadrant

It’s the position of the different evaluations that you’ve selected on two axes :

  • functional coverage : the value used on the X-axis is the weighted mean of all the criteria of the template, except the criteria of the Maturity section ;

  • Maturity : the value used on the Y-axis is the weighted mean of the criteria of the Maturity section, imposed by the method.

The ellipse, corresponding to the evaluated software, are clickable zones that redirect you to the visualization of the details of each evaluation.

Please note that this type of visualization requires that your browser respects the SVG standard.

You can save the QSOS quadrant on your hard drive by using the save function of your browser.

Exporting a comparison into OpenDocument formats

Export into OpenDocument formats button

Export into OpenDocument formats button

On your comparison management page, you can export it into the following OpenDocument formats :

  • spreadsheet : ODS format ;

  • presentation : ODP format ;

  • text : ODT formats.

Exporting into ODS format

On your comparison management page, a click on the Export into ODS triggers the generation of the export of your comparison into the OpenDocument Spreadsheet format.

You can save the result as an .ods file on your hard drive.

Spreadsheet exported by O3S

Spreadsheet exported by O3S

The exported spreadsheet contains several tabs :

  • Home : the Front-Cover of the document presenting the metadata of the comparison and of its ODS export (date, template version, tabs’ presentations and license) ;

  • Synthesis : tab synthesizing the comparison in terms of scores and allowing to modify the weight of the criteria ;

  • Criteria : explanation of the criteria used in the comparison, based on the data of the template ;

  • a tab for each evaluated piece of software : presenting the details of the evaluation (metadata, scores and comments).

This dynamic comparison can be used autonomously to customize your comparison by modifying the weighting.

Please note that in order to guarantee the community aspect of the effort provided to make this exported document (creation and modification of the template, creation and modification of the evaluations, development and maintenance of the tools XulEditor and O3S), it is distributed by the QSOS project under the terms of the GNU Free Documentation License11.

Exporting into ODP format

On your comparison management page, a click on the button Export into ODP triggers the generation of the export of your comparison into the OpenDocument Presentation format.

You can save the result as an .odp file on your hard drive.

Presentation exported by O3S

Presentation exported by O3S

The presentation is composed of different types of slides :

  • the Front-Cover of the presentation ;

  • the table of content slides to position and organize the other slides ;

  • the slides relating to the scope of the comparison : list of analyzed solutions, presentation of the template (FreeMind mindmap and an explanation for each main section of the template) ;

  • for each analyzed solution, slides giving more details (presentation of the project, minmaps and text to be completed for every main section of the evaluation) ;

  • slides relating to the comparison of the solutions (radar charts and text to be filled for every main section of the evaluation, QSOS quadrant and text to be completed) ;

  • slides relating to the license of the presentation and to the credits to the QSOS community (authors of the evaluations used to generate the presentation’s backbone).

It is a backbone that can be used to produce a final document by entering your analysis and your synthesis in the text zones to be completed.

Please note that in order to guarantee the community aspect of the effort provided to make this exported document (creation and modification of the template, creation and modification of the evaluations, development and maintenance of the tools XulEditor and O3S), it is distributed by the QSOS project under the terms of the GNU Free Documentation License12.

Exporting into ODT format

On your comparison management software, a click on the Export into ODT button triggers the generation of the export of your comparison into OpenDocument Text format.

You can save the result as an .odt file on your hard drive.

Report exported by O3S

Report exported by O3S

The report is composed of different chapters :

  • Introduction : chapter briefly presenting the purpose of the document as well as the QSOS method and containing text to be completed ;

  • Used analysis template : presentation of the template (FreeMind mindmap and details on every main section of the template) ;

  • Identified solutions : presentation of the scope of the comparison and details on every evaluation (presentation of the project, mindmaps and text to be filled for every main section of the evaluation) ;

  • Synthesis : comparison of the different solutions (radar charts and text to be completed for every main section of the evaluation, QSOS quadrant and text to be completed) ;

  • Appendix : presentation a little more detailed of the QSOS method ;

  • Credits : attribution to the authors of the evaluations used to generate the backbone of the document.

It is a backbone that can be used to produce a final document by entering your analysis and your synthesis in the text zones to be completed that are highlighted in the document.

Please note that in order to guarantee the community aspect of the effort provided to make this exported document (creation and modification of the template, creation and modification of the evaluations, development and maintenance of the tools XulEditor and O3S), it is distributed by the QSOS project under the terms of the GNU Free Documentation License13.

Appendix : DrakkR framework

QSOS is a sub-project of the DrakkR initiative aiming to build a free framework dedicated to the open source governance within companies and administrations.

In addition to QSOS, dedicated to the assessment of free and open source software, DrakkR is also composed of other methods and tools to implement such a governance.

DrakkR Framework

DrakkR Framework

  • OSC (Open Source Cartouche) : sub-project dedicated to the unique identification of a version of a piece of open source software and the management of its metadata ;

  • ECOS (Evaluation of the Costs linked to Open Source) : sub-project regarding the evaluation and the calculation of the Total Cost of Ownership of a piece of open source software as well as the Return Of Investment of a migration ;

  • FLOSC (Free/Libre Open Source Complexity) : sub-project providing method and tools to evaluate intrinsic complexity of open source components ;

  • SLIC (Software LIcense Comparator) : sub-project dedicated to the formal description of open source licenses and its relative compatibilities ;

  • SecureIT : sub-project dedicated to the management of security notifications in open source software.

Visit the web site of the project to go further : http://www.drakkr.org.