Documenting components on the Open Platforms Portal

This tutorial presents in details how to use the Open Platforms Portal to document components. It presents the process to create or edit components, present the different categories of components and describes in details the different fields of the categories.

This tutorial can be used both by editors and end users of the Open Platforms portal as the presentation of categories and field can be useful to better understand the available documentation and to look for information

  • Latest version ID: 1.0
  • Tags: ,
  • Latest update: July 16, 2014
  • Developed by: inno for the BUTLER project and IERC AC1
  • Contact name: Bertrand Copigneaux
  • Relations:
    • Open Platforms Portal (more details)
      • Relation type: Reference relationship
      • Validation:

        This tutorial references the Open Platforms Portal, which is described as a tool.

        No validation / declarative.

      • Completeness of the relation: 100%

Intellectual property rights (IPR)

Creative Commons License

This work is licensed under a Creative Commons Attribution 4.0 International License.

Introduction and Requirements

This tutorial presents in details how to use the Open Platforms Portal to document components. It presents the process to create or edit components, present the different categories of components and describes in details the different fields of the categories.

This tutorial can be used both by editors and end users of the Open Platforms portal as the presentation of categories and field can be useful to better understand the available documentation and to look for information

To document components you need to have access to the Open Portal back office. The back office of the portal is available at this address

To join the initiative and get credentials to loggin, please contact us through the contact form, indicating the organization you work for and/or the project(s) you're involved in.

Components Categories

Different categories of components can be documented on the Open Platforms Portal:

  • Use Cases: This category documents scenarios of use of IoT technologies. This can include high level application domains (Smart Home) or individual detailed scenarios (controlling home multimedia system based on user location). See more
  • Libraries: This category documents software libraries made available as Open Source or web services made available as Open API (and possibly Open Source), that provides reusable components that can be used for developing IoT applications or other enablers. See more
  • Tools: This category documents Open Sources software tools that can be used to facilitate the development of IoT applications and enablers (example: IDE, debugger and diagnostic tools…).See more
  • Tutorials and Reviews: This category represents tutorials on how to use the different components (Libraries, APIs, Tools, Applications, Models…) of the platforms; or third party reviews of one or more component(s) documented in the portal. Third parties reviews (of a single component) or comparison between different components are important to validate the quality of the components documented and to provide alternative views by independent actors. See more
  • Standards, Protocols, Models: This category documents standards, protocols and models that can be used in the design of IoT applications and enablers. (Communication protocols, architecture models, ontologies…). See more
  • Applications and Deployments: This category documents IoT deployment, or open source or closed source applications using some of the components documented in the portal in a use case documented on the portal. See more

Creating and Editing Components

This section presents how to create or edit a component, list the key fields to be filled, and how to publish the component.

Creating or Editing a component

The back office can be used to create new components or edit existing ones.

  1. Open the Open Platforms Portalback office.
  2. Open the type of custom category of the component to which you wish to add, or edit a component.

Creating a component

  1. Click Add New
  2. createNew

Editing a component

  1. Search for the component to which you wish to edit.
  2. Click Edit.
  3. tuto_relations0_edit

Key fields to document

Once you have created or open a component for edition, you have to fill specific fields corresponding to different information about the component that you document. In the back office, the description of the content expected for each field is described below each custom field. Make sure to document your component as accurately as possible as it will facilitate it's reuse and adoption by third parties

CustomFieldsPortal

We describe in details each field and the expected value later on in this tutorial (see section 4). In this section we present the most important fields to document to enable the reuse of your component.

  1. Overview:

    Abstract description of the component documented. Should be a general overview to easily understand (even for non experts) what the component provides, why and what it can be used for. The content of this field will appear in search results and should be attract potential users to your component

  2. Description:

    Depending on the type of component that you document, the Description field can have different names: Full Specification, Content, or Description. This field should contain the main documentation of your component, or a link to existing documentation when it is available. If your document is already well documented elsewhere it is not necessary to duplicate information here, a simple link to an up to date and maintained documentation is better than an outdated documentation on the portal.

  3. Intellectual Property Rights:

    Short explanation of the licensing scheme / Intellectual Property Rights associated with the component documented and the documentation in itself. Ideally with reference to the full licensing scheme (legal document). This field is important to enable potential users to clearly know the condition under which they can or cannot use your component.

  4. Service Level:

    Description of the Service Level provided by the component developer for the component (support, maintenance, evolutions…). By providing information in this field, you can rapidly ensure to potential user that your component is maintained and will evolve. Maintenance and evolutions are key to the take up and re-use of software components. This field can also be used to provide a quick link to your support.

  5. Relationships:

    Add one or more relationships to other components documented in the Open Platforms Portal. Relationships are essential to enable the discovery of your component and to identify the links with the ecosystem. A complete tutorial on how to create relationship is available here.

  6. Tags:

    Tags provide a useful way to group related component together and to quickly tell readers what a component is about. You can define tags, either by choosing from the most used tags or by defining your own if you need to. Tags also make it easier for people to find your content.

  7. Examples:

    Detailed examples of use of the component (including source code) or link to detailed documentation of examples. Ideally try also to add examples to your description.

Publishing a component

To save and make visible your newly define relationship click Publish in the edition page of the component you are documenting

tuto_relations11

Field to document

This section presents the different fields to document a component in the Open Platforms portal.

Field to Category mapping

The following table present a mapping of the fields available to document for each component. The field in red, are required and must be documented.

mapping

General Fields

The content of these fields is visible in the General Information tab of the component documentation.

generalTab

Overview

Abstract description of the component documented. This should be a general overview to easily understand (even for non experts) what the component provides, why and what it can be used for. The content of this field will appear in search results and should be attract potential users to your component

Latest Version

In this field you can refer to the specific version of the component you are documenting (for Libraries, Tools, Standards, Application and Deployments...), or use this field as a version of the documentation in itself (for Tutorials, Use Cases). Version documented: Major.Minor.Revision

Developped by

Person and/or Organization and/or Project behind the creation of the component.

Localization

This field, only used for documenting deployments refer to the localization of the deployment.

Source Code Repository

This field available for Libraries, Tools, Tutorials and Applications. It can be used to provide a link to an external repository where the source code of the component is available.

Download URLs

This field available for Libraries, Tools and Applications. It can be used to provide links to the compiled versions of the component for different platforms or Operating Systems.

Intellectual Property Rights

Short explanation of the licensing scheme / Intellectual Property Rights associated with the component documented and the documentation in itself. Ideally with reference to the full licensing scheme (legal document). This field is important to enable potential users to clearly know the condition under which they can or cannot use your component.

Description Fields

Depending on the type of component that you document, the Description field can have different names: Full Specification, Content, or Description. The content of this field is visible in the Description tab of your component page.

DescriptionTab

This field should contain the main documentation of your component, or a link to existing documentation when it is available. If your document is already well documented elsewhere it is not necessary to duplicate information here, a simple link to an up to date and maintained documentation is better than an outdated documentation on the portal.

Description

This field is available for Use Cases, and should provide a general description of the use case.

Full Specification

This field is available for Libraries, Tools, Application and Deployments, and Standards and Models and should provide a description of the component Including:

  • important methods and features
  • Install and set-up process
  • Detailed documentation of the component
  • or link to detailed documentation

Content

This field is available for Tutorials and Reviews, and should provide the actual content of your tutorial or review.

Service Level Fields

The content of these fields is visible in the Service Level tab of the component documentation.

ServiceLevel

Service Level

Description of the Service Level provided by the component developer for the component (support, maintenance, evolutions…). By providing information in this field, you can rapidly ensure to potential user that your component is maintained and will evolve. Maintenance and evolutions are key to the take up and re-use of software components. This field can also be used to provide a quick link to your support.

Technology Readiness Level

Estimated technology readiness level of the component documented. Technology readiness levels (TRLs) are measures used to assess the maturity of evolving technologies (devices, materials, components, software, work processes, etc.) during their development and in some cases during early operations. This field is a self assessment. however, details of the technology readiness should be documented in the service level section.

Reuse Readiness Level

estimated Reuse Readiness Level of the component documented. This field is a self assessment. however, details of the technology readiness should be documented in the service level section.

Security

Description of the Security Mechanisms provided for the component (threats analysis and responses). This field is a self assessment.

Other Fields

The content of these fields is visible in a specific tab of the component documentation.

Examples

This field is available for Use Cases, Libraries, Tools, Standards and Protocols and Applications and Deployments. This field can be used to provide detailed examples of use of the component (including source code) or link to detailed documentation of examples

Business Model

This field is available for Use Cases and Applications and Deployments. It can be used to provide a description of the potential business model implications behind a use case or on element of the business model of a deployment, such as:

  • Market analysis
  • Value Chain and stakeholders
  • Value propositions for the different stakeholders
  • Potential business model and sources of revenue

Tags and Relationships

To correctly reference the component you documented, and ease it's identification it is important to define both tags and relationships.

Tags

Tags provide a useful way to group related component together and to quickly tell readers what a component is about. Tags also make it easier for people to find your content. You can define tags, either by choosing from the most used tags or by defining your own if you need to. The size of the tags in the list indicate how often it appears in other component descriptions

tags_portal

Relationships

Add one or more relationships to other components documented in the Open Platforms Portal. Relationships are essential to enable the discovery of your component and to identify the links with the ecosystem. A complete tutorial on how to create relationship is available here.

Further reading

The following element should help you learn more about the open platform portal:

Service level

This tutorial is a first version, it will be updated as the Open Platform Portal evolves