Developer Space/Components

From wiki.gpii
Jump to: navigation, search

Executive Summary

This document contains an accompanying user guide and developer documentation for the GPII Developer Space Component Repository, which is online as part of the GPII Developer Space at. If you are interested in contributing, visit the site directly at http://ds.gpii.net/components and refer directly to the relevant section in this document.

We constantly extend this repository with new components. The repository allows structured search in a comprehensive list of building blocks for Assistive Technology development and accessible IT implementations. The repository is as inclusive as possible, addressing different needs and solutions by holding a diverse set of software and hardware. The components listed on this page fulfil some minimal requirements for documentation and categorisation that we define in this document. If you want to add a component to the list please go to GitHub @dspace-projects account, drop a mail on the DSpace Mailing List or post to our twitter account at @GPII_DevSpace.

The goal of this public deliverable of the Prosperity4All Project is to provide particularly technical documentation about the background of the site and the curation process, which aims to be transparent, sustainable and scalable. The document is the last one in a range of documents (D202.1 and D202.2) where we have described, how we created and designed this repository and looked at technical convergence of components through standards and APIs. If you want more detailed information about the underlying architecture of the whole Developer Space refer to architecture documentation (D201.5) as this document documents particularly the component listing. Additionally, you should visit and browse the actual main deliverable of the project (the Developer Space), which is online at http://ds.gpii.net/.

Background and Related Efforts

The component repository is not a unique effort in the sense that it collects accessibility related components. However, it differs from existing efforts in multiple ways. Even before the efforts started in this project the spotlight / featured tools and components on the RaisingTheFloor web site provided a listing of developer targeted tools and components. The GPII Developer Space incorporates this repository along with other developer-targeted content. RaisingTheFloor is committed to curate this content beyond the project via the GPII Developer Space. The original listing also contains project specific listings like the AEGIS: Overview of demonstrators . It is the goal of the GPII Developer Space to provide a platform for such listings in the future and interlink open project results from commercial or academic endeavours in more sustainable way. Today AEGIS lives on on GitHub e.g. as the Aegis Demos repository. From GitHub developers can easily fork and use results. We want to encourage projects to bring content to places where the developers actually are, without creating a new place that diverts traffic. Thus, we provide an interface that just provides an alternative interface to existing sites. The same goes for technology specific efforts like the W3C WAI Component Gallery. We were easily able to incorporate most content as it was hosted here. We also depend on external activities like Project A11y to identify open source content. The biggest difference of the component repository to other comparable collections is that we have identified over 1000 accessibility related open source components that we started to categorize on https://ds.gpii.net/develop/components .

The Interface for Searching, Browsing and Bookmarking Components

Screenshot of the Developer Space Component Repository

The above figure shows the current interface to the component repository with more than 700 curated component entries (the rest is still in the moderation queue). In the main part (1) a summary of different components. For components that were imported the number of followers (stars) and code forks is shown as an indicator for the popularity and distribution is shown (2). Additionally, users can quickly bookmark or rate a component (3).

Instead of having many subcategories (like tools, code, hardware) the interface relies solely on a so-called "faceted search". The search field (4) can be used to query the collection. The user may narrow downs this collection by selecting facets that are shown on left hand side of the screen (5). Based on earlier user research we currently support filtering by the following facets:

  • Technology: mostly the used programming language
  • Licence: open source licence type specifying permitted distribution
  • User Needs: major disability categories
  • Type: related to the usage as independent developer tools or e.g. as programming framework
  • Technique: what strategies to solve accessibility needs can be applied using the component

Example selecting javascript components that support adjusting the contrast


Using this interface the user can quickly apply various browsing strategies such as exploring all MIT licenced components that help with physical disabilities or specifically searching for a reactive web component that changes contrast on a web site.

Links to components shown at the bottom of the Accessibility Masterlist entry

The site consequently interlinks content providing a rich browsing experience. By clicking e.g. on a technique the user is redirected towards the Accessibility Masterlist, which in turn lists all possible components but also other educational material. Through the applied categorization the site, thus provide a rich experience and fosters learning and exploration. It links from the theoretical background to practical material such as the components, to motivate real implementations.

Roles within the Developer Space

The concept of roles as we will describe it here is the basis for access control and defining content management processes.

Users

Users of the GPII Developer Space are described using the following five "epics":

  • I develop AT and I want to make my product more accessible
  • I want to make an accessible website
  • I teach and research accessibility
  • I make policies on accessibility
  • I want to get the latest on accessibility

While the searching the GPII Developer Space can be done spontaneously (and should not require any documentation or a technical role), we also want to engage those users as prosumers. Logged in users contribute in multiple ways to the site:

  • Provide useful comment and feedback on components
  • Suggest new components and other content
  • Provide feedback on the overall site

Editors

Editors are community members or power users. Their main work is to organize the collection of resources, thus adding value beyond quantity. In this document, we describe how Editors should categorize content.

Editors are typically volunteers from the RaisingTheFloor consortium and the overall GPII. Categorizing one thousand components needs a large number of volunteers initially. Currently partners from the funded Prosperity4All project took on this job. We believe less volunteers are needed once most of the content is categorized.

Curators

Curators are needed to release components. The role of the Curator is to assure the quality of the content concerning both the usefulness and the legal compliance of the content.

The checks to be done are described in the last section of this document. It should suffice to have a single Curator for the component registry. It makes sense in terms of quality assurance to separate curation from editing. Curators should be contractually bound to the operator of the site (RaisingTheFloor International) in order to protect the operator from potential legal complications by enforcing some rules. Curators could also be seen as community managers or moderators. They have the right to modify, release or withdraw any content.

A special task for the Curators is maintaining the GitHub interface to the developer space as well as adding content into the categorization cue for the Editors.

Administrators

The role of the Administrator is to maintain the necessary software, define roles and access policies and to oversee the curation process.

One important prerequisite of the whole system is that the Administrator can assign roles to users. In case the system needs to scale, also other roles might assign less privileged roles. Currently we are envisioning that most users do not need special privileges, so the Administrator knows and manages all Curators and Editors.

Currently the Administrator is meant to be a web developer with skills in HTML, PHP and Drupal. The development of the code for the repository is coordinated by RaisingTheFloor International as part of the overall Developer Space with contributions by KIT (repository imports), Pushing7 (Drupal integration) and Illunion (feedback).

The overall Developer Space site is built on Drupal 7 technology (for the underlying architecture please refer to D201.5 of the Prosperity4AllProject). The component repository specifically relies on the Search and Facets API that provides the necessary interfaces for efficient browsing via an Apache SOLR server. The curation scheme above is implemented using the Workbench Moderation module. We share those parts with the other content of the Website

. Example of developer contributing content

Administrators should give special attention to the Github Feeds Importer that is described as part of this document.

Adding Components

Suggesting New Components

Users can suggest new components using the issue tracker on GitHub: https://github.com/dspace-projects/additions/issues/ .

Additions should be shared as direct links to GitHub repositories if possible. However, projects (source code) hosted in other places is also welcome.

Example of developer contributing content

As explained above, the Developer Space exists to feature a diverse set of components that an implementer can build into their products or can help them improve their product in other ways (e.g. by testing). The listing's lifeblood is from suggestions from the community. As most open source development has moved to GitHub as a platform (Google Code as well as Microsoft Codeplex have been archived with migration paths to GitHub), it became more and more apparent that we need to support a GitHub centric workflow to cover the majority of open source developments. This includes particularly component from the GPII projects, such as Cloud4All and Prosperity4All.

Curators may schedule new components scheduled for moderation by "staring" the project via GitHub's native interface. This provides an easy two-click workflow to review new suggestions. Using the Developer Space user account in GitHub, the Curator can follow the link in the issues (or also e.g. an email with a suggestion), quickly assess the relevance of the suggestion (not categorizing at this point) and click the "star" icon. The item will be automatically scheduled for addition on the Developer Space website (see below).

Staring component on Github to trigger inclusion


Another important aspect of this workflow is that it allows us to disseminate components over GitHub's social network. Additions to the Developer Space will be fed to all followers on GitHub automatically via the timeline visible on GitHub's homepage to signed-in users:

Screenshot of user riedel of mainpage of github.com

Strategies for finding new components

One important feature of the staring feature is that it works both ways. In a addition to having followers, that are informed about new findings, the Developer Space Curators are informed about new findings from the people in our social developer network. While the automatic suggestion feature of GitHub mostly focuses on popular, content that is either too unspecific to accessibility or already included, the simple timeline view helps to find new things quickly as we are following accessibility related developer profiles (see screenshot)

Filtering user profiles for interesting components

Another strategy to find new content is to identify early adopters of accessibility related technology (e.g. by following git commits to knowledge basis such as the A11Y projects). By listing all starred components from their GitHub profiles Curators are quickly able to find new components (see below). If the user shares relevant findings, Curators will continue to follow this user to get updates via our own timeline.

Github timeline for Developer Space curation user

Understanding the Importing and Updating Pipeline

Drupal Feeds Plugin

New GitHub projects are periodically imported via a Feeds plugin on ds.gpii.net

Importing task aumatically run every 3 hours

The whole workflow for aggregating new GitHub projects is backed by a Drupal module that was developed at KIT in the Prosperity4All project to particularly fit the needs of the Developer Space (but can be used beyond this). The module supports two interfaces to GitHub. One remote entity interface that allows interfacing GitHub content as Drupal entities via GitHub’s API and one interface to autofill content using fields from GitHub.

Currently the Feed plugin sources the following information automatically from GitHub and maps it into Drupal:

  • Component name
  • Component author
  • Short Description
  • Readme file
  • Licence
  • Programming Language
  • Descritive Tags
  • Number of stars
  • Number of forks
  • Website link

The Mapping of GitHub information to DSpace

We use the same internal mapping logic to extend the Feeds interface as is used to import new component listings that are displayed on the GPII Developer Space. The API particularly supports the pagination of queries to Githubs open API and calls to fill out child elements such as the description.

The listings are automatically updated. Newly imported content is not published immediately, but must undergo categorization first. We use the GitHub URL as a unique identifier for updates. This means that renaming of repositories might lead to duplicates. Screenshot shows the current mapping of the importing workflow that might be adapted to future needs.

Configuration of the github mapping

In order to support such a large number of queries we need to obtain a GitHub API token. The API token can be configured inside the Drupal configuration page and should be copied from the GitHub account settings of the GitHub account. The API token also identifies the account that we use for importing. Future versions might support an even more integrated workflow, e.g. for un-listing components simultaneously or for feeding suggestions via the web interface directly to the issue list. The current source code of the components is available at: https://github.com/dspace-projects/ds.gpii.net

Using the Feeds Importer, we can add fields to each component listing that will be retained during synchronization. This particularly includes the categorization (see below)

In addition, Editors and users can add other content such as reviews and comments to the component. Components can also be interlinked throughout the site, e.g. in tutorials or through the categorization.

Editing and Categorizing Components

Once the component is successfully imported, Drupal adds it to an editing and curation queue as unpublished content. The Editor prepares the document for publication and puts it into the curation queue where the Curator schedules it for publishing (see next section).

Editor picks item from Queue

The following workflow should be followed:

0. Reading the description of the component

1. Deciding if it is a relevant component at all

2. Categorizing the component type

3. Checking if the component is particularly addressing a need of one of the major disability classes.

4. Specifying the type of solution in terms of the Accessibility Masterlist.

5. Checking if the components relates to a requirement as specified by EN 301 549

6 Mark the component for publishing and go to the next one

The screenshot below shows the interface for categorization.


Categorization Interface

Type

Many developers come with a certain problem at hand. This normally means that they are looking for a specific kind of thing; they can embed into their software, use for development or add e.g. as extra hardware. We currently have identified the following classes:

  • Libraries & Snippets: independent components, that can be embedded
  • Framework-specific: things that work in the context of specific development frameworks
  • Framework: a complete set of APIs and components
  • Testing & Development: tools that help during development to increase quality or save time
  • Hardware: things that need to be produced physically
  • Web API: hosted APIs that can be used easily

We have found that these categories or combinations of them help finding fitting components for many use cases. They might be efficiently used in combination with the full-text search (e.g. looking for "framework-specific" (facet) "react" (full-text components). "Over-tagging" might lead to many irrelevant hits (e.g. every "Framework" contains "Snippets and Libraries", but most commonly it is used as whole). "Under-tagging" might lead to few things being categorized. We provide an "other" category to identify missing categories, but this should not be used too often: the Editor should specify in the comments why something was hard/impossible to categorize).

Note: We are focusing on open source components, while also listing commercial solutions that help developers. Particularly the last item can also contain references to non-free interfaces. Sometime the licence filter is misleading as the code for accessing the API is free but you need access to commercial services (see e.g. https://f-droid.org/wiki/page/AntiFeatures ). The same might apply for hardware. The minimum criterion should be that those things could be openly built into existing or new solutions.

Needs

In Developer Space/Standards we have looked at many categorization schemes. While most schemes fall short of describing the specific needs of a person and do not really address the idea of inclusive design or inclusion by design, particularly easy categorization helps novice developers to understand the domain. The following categories can be selected by users of the DSpace:

We understand that this approach of focusing firstly on "major" classes may often leave out the tails of the tails and sometimes might lead to addressing "red flags" only. However, providing those major categories helps developers finding what they want more easily. Categorization is semantically always discrimination. With a faceting approach we, however we offer this only as one way of browsing and refining. In addition, multiple facets can be selected: e.g. "Blind" and "Deaf", but we cannot ensure that the component might help a deaf and blind individual, however it will narrow down the number of items. This narrows down the search space rapidly.

Solutions

As stated above the Accessibility Masterlist is our own developer focused ontology for categorizing solutions. A component should be part of a solution to a problem commonly found in accessibility. The developer space constantly looks for new strategies and solutions, however, the list as it is currently maintained, contains most individual strategies that have been followed. Categorization of components is a good way to look constantly for new approaches. It makes sense for an Editor to be become familiar with all Accessibility Masterlist items on a high level while categorization. A good starting point is to look at existing similar items that are already categorized.

Two problems typically occur. Firstly, the item only helps the development process (in contrast to the targeted end user) and so can be widely used. This is true for many testing tools. It is difficult to specify concretely the addressed solution. However, we do not want to list tools such as common continuous integration frameworks with no specific link to accessibility. So tagging a solution is also a check for relevance. One solution is finding more fitting subcomponents (e.g. accessibility related plugins or workflows) to be listed here. Many testing and development tools are currently tagged as "Transform content to conform to accessibility standards", although still manual effort is needed. This seems acceptable in the context of this component. Tagging a testing tool (which helps minimizing accessibility error) with the item "Help Minimize Errors" is likely not be correct as solution should be thought from the end users perspective. Therefore, the Editor should be sure that he understand the description linked to the tag, in this case e.g.: "This is an overarching feature that includes many error-minimizing technique. [...]Any disability may increase the risk of an error, and may make it difficult to recover from mistakes. This feature helps to reduce the number of errors "(see https://ds.gpii.net/learn/accessibility-masterlist/help-minimize-errors)

The second problem is that many inclusive AT frameworks provide different solutions. The Editor should not add too many solutions to general frameworks. Such categorization should rather be done to specific tutorials and components linked to that framework that address solutions specifically. A typical user using the search interface will most probably not immediately understand the link between a general accessibility framework such as Fluid Infusion and e.g. cognitive disabilities, although it might provide solutions implemented in that framework. The Fluid Progress Component using that framework could however be categorized and a link should be provided to the underlying framework.

Procurement Requirements

A separate categorization strategy for procurement scenarios that we are following does not originate from the user research on the search interface, but was motivated particularly through potential business cases and the work on standardization (and consequently regulation). The process initiated by the European Mandate 376 will have a major impact on procurement of IT with relationship to accessibility. Many companies will be faced with the need to fulfil technical requirements, that are specified as part of standard EN 301 549 "Accessibility requirements suitable for public procurement of ICT products and services in Europe". The standards is aligned with existing standards like W3C WCAG 2.0 (which is a subset of this categorization). Consequently the standard is quite complex for categorization. Integrating this part is the latest addition to the Developer Space component repository and therefore still incomplete and under testing.

The idea is to support a procurement work flow that starts with the creation of a "Call for Tenders" as it is supported by http://mandate376.standards.eu/ . The typical output will contain references to technical requirements that need to be evaluated for someone answering the tender (http://mandate376.standards.eu/procurement-stages/evaluating-proposals). This amounts to a gap analysis for many existing products. By tagging components (and other resources in the GPII Developer Space) by requirements from the standard, we can extend this work flow to enable companies to answer to tenders by extending their products through new solutions. We see this an important contribution for globally improving accessibility. It provides furthermore an important potential entry-point to the GPII Developer Space.

While it is an intriguing idea that anyone can make their products fit for public procurement just by including bits of open source software, this raises far too high expectations. Therefore we decided in collaboration with the standardization task force to add a qualification attribute to the categorization interface (see screenshot below). Most of the time many steps are needed to fulfil a technical requirement for accessibility. One step could be the inclusion of a component listed in the GPII Developer Space. We want to express that by explanations and a level of support mapping. There are four possible levels of support.

  • (L1) An item provides background information on disabilities, barriers in technologies, or how AT helps to overcome these barriers.  The item can also be a piece of AT (software, hardware, or documentation) which can be used by a developer to get a feeling about barriers and how to overcome them with AT, and to test their product for compatibility with this piece of AT.
  • (L2) An item provides guidance in how to comply to an EN provision, but not in sufficient detail so that a developer could carry out the necessary steps without other sources of information. This level of support also applies to test tools (or documentation for them) that can assist in checking for compliance to one or multiple EN provisions. This includes tools that check for compliance in an automatic or semi-automatic manner.
  • (L3) An item provides detailed instructions on how to comply with an EN provision, but this will only result in a partial fulfilment of the provision. In addition, other measures need to be taken to fully comply with the provision. This level of support resembles that of the “Advisory Techniques” in WCAG 2.0.
  • (L4) An item provides detailed instructions on how to comply with an EN provision, and by doing so this will result in a full fulfilment of the provision. This level of support resembles that of the “Sufficient Techniques” in WCAG 2.0.

Ds.gpii.net node 3743 edit en301549.png

Curating and Publishing Components

While the GPII Developer Space is a community initiative, we have learned the hard way that providing quality needs structure and individual commitment. Especially in the early phase towards sustaining the project, a tight organizational structure and clear responsibilities are important. Raising The Floor International (RtFI) is committed to host the the Developer Space. Therefore at the moment administration and curation are roles mostly implemented by RtFI. As the community grows this concept needs to certainly scale, but it currently requires close coordination. The curation role for the developer space repository especially means taking responsibility for sustaining the content and consequently for the sustainability of the site.

Minimal Requirements for Including Components

By selecting potential components and by publishing components Curators need to define the scope of the site. It is important to understand that the Developer Space component repository should be focused, complete in certain areas and complete in breadth of relevant areas in the AT domain. We have opted globally for a very inclusive strategy that has found more than one thousand interesting components. We are still missing relevant ones and will most certainly have quite a few in the list that might not have much value. However it is important that we provide particularly information and also software that addresses the tails of the tails, while ensuring the attractiveness for newcomers to the domain. This is why we will list as many components as possible and try to address quality by providing indicators through rating and metrics that allow the users to judge quality.

There are minimal requirements. Foremost we have to clarify the legal and ethical consequences of including content. As we are mostly listing open source, we normally do not have copyright issues as long as attribution and links are provided to the original content. However, particularly for free-to-use or commercial components the content should be checked quickly, if the content (images, text) can be legally displayed on the site.

Other than that there should be a minimal documentation and linked information that allows judging quality quickly. This also includes that overly promotional postings should not be allowed, particularly for commercial content. Instead of rewriting content (eventually leading to responsibilities regarding correctness), the Curator should delay listing if necessary and clarify aspects with the original publisher. This includes copyright, missing information and ethical issues with descriptions alike.

Within the internal process, the Curator should perform final checks,for if the categorization seems to make sense or if the Editor left comments. In this case of doubt a second Editor should be asked to review the categorization. Normally, after a quick check the Curator can accept the categorized components. Overall this process should take two minutes per edited component maximally to scale.

Scheduling for Publication and Maintenance

Once an Editor has changed the state to "Needs Review", the item will appear in the queue of any user with a Curator role. The Curator checks the categorization for soundness (see above) and might resolve any comments left by the Editor. Once this is done the Curator schedules the content for submission. We expect Curators to work perhaps once a week on components, but we want to have the repository grow as people visit the site regularly. Accordingly, the publishing of the content is scheduled, so that users see new content each day. The image below shows recently scheduled content. This step is particularly helpful is if content is dynamically updated on the front page showing new additions. Curators should curate the structure of the site and actively interlink content based on their knowledge that goes beyond categorization (e.g. linking tutorials, etc).

Curators are also in charge to check feedback delivered via the rating and feedback forms related to the listing. Particularly, if comments are related to wrong categorizations or missing links, Curators should review component listings.


Ds.gpii.net admin workbench needs-review.png

Summary and Future Work

In this document we defined the roles and processes as well us the underlying technical framework for the components repository that was made publicly available as part of the Prosperity4All project. An up to date version of this document can be found at: Developer Space/Components and will be refined continuously beyond the project. This document is part of the goal to sustain the development and the maintenance of the GPII Developer Space. All the categorization schemes have been build upon careful evaluation and initial testing on various prototypes. Yet we still expect changes to be necessary over time. Therefore we have build a structure that is modular and can hopefully be also migrated easily to other technologies.

We tried to document the considerations made when building the present structure and hope that is will help both scaling and refining the site in the future. The Developer Space Component repository will for sure need such constant refinement. Particularly we have multiple items on our wish list that we want to include in the future:

  • Integration of other hosting sites like SourceForge or BitBucket
  • Badges for listings (based e.g. on http://shields.io/) that make it possible to take categorization back to the original documentation and provide links into the GPII Developer Space
  • Crawling of images as thumbnails and featured images
  • Incentivation and gradual Qualification based on a gamified point system for Editors
  • Improved integration with other sites, particularly with http://mandate376.standards.eu/ that provide interlinking possibilities.
  • Integration with continuous integration/testing and package installation like npm or nuget based on automation

We are currently migrating the source code and the issue tracking for all components. We are inviting contributors to continue to develop and test functionality technically. We are happy feedback (e.g. on the discussion page for this article or the Mailing List).