Semantic Web Based Context Adaptable Generation ofProduct Specific Documentation

Andrei MiclausTECO, Karlsruhe Institute of

Technology (KIT)miclaus@teco.edu

Till RiedelTECO, KIT

riedel@teco.edu

Jack UnseldTECO, KIT

unseld@teco.edu

Deepak DhunganaSiemens CT Austria

deepak.dhungana@siemens.com

Michael BeiglTECO, KIT

michael.beigl@kit.edu

ABSTRACTAs users and developers have started to put the Internet ofThings to good use, the approach to documenting applica-tions has not evolved to handle the created complexity. Asitems, devices and systems become more customizable andadapted to their users, their documentation still lacks be-hind. Particularly documentation that covers the contextualbehaviour and specific configuration of artifacts is needed.

We design a system that leverages semantic web technologiesto create ”smart”documentation on the basis of model basedsystem descriptions and heterogeneous data sources, whichare needed to create valuable and up-to-date documentation.

Based on two scenarios we show the benefits for both the de-velopment cycle and the user experience of Web of Thingsapplications. The paper presents a mashup of internet ofthings, model driven development, semantic web and HTML5MVC technologies for generating context-sensitive documen-tation.

1. INTRODUCTIONAn increasing number of smart, mashable and customizabledevices reach the market. While traditionally, systems werebuilt from single vendor components, more and more end-users create their own systems from heterogeneous devicesand software to fulfill their needs. The final product is cre-ated by the user.

Unfortunately, in such complex interaction patterns even asingle component becomes increasingly difficult for a humanto understand and configure. Taking the example of end-user installed home automation systems it can be shownthat the overall conceptual model plays an important rolein user acceptance when setting up such systems [3]. Sub-sequently, documentation packaged with the devices would

need to provide appropriate information. However, today’sdocumentation cannot take the current application contextand user experience into account and thus fails to provideappropriate support [2].

User

Data Resource Mashup

Configuration

Feedback

THINGS

Developer

Smart  Template  

Gear  

Rims  

Frame  

Bike  Context  Model   Text  

Descrip5ons  

Context  adapted,  up-­‐to-­‐date  Informa5on  

Documents

Instant  Help  

Semantic web Membrane (Adapter) Change Notifications

Figure 1: High level interaction overview.

Furthermore, product manufacturers also need to deal withthe increasing complexity of the product documentation whendelivering pre-customized items. Often they burden usersto make sense of a documentation describing entire productfamilies instead of the product variant they acquired.

To address this problem, we envision a document generationsystem that creates a data mashup from different resourcesaccording to ”smart” documentation templates. As seen infigure 1, the developer configures the “smart” template in-stance, providing data source locations for a specific productvariant. The smart template in turn queries the data sourcesusing semantic web technologies and generates the up-to-date documentation. Using notifications, re-generation ofthe documentation can be automatically triggered when un-derlying data sources change. A recent study showed thatsuch document generation may bring a further benefit: userswill read the documentation more carefully than a static oneif they are told that it is generated by such a system [11].

The system is designed to create personalized, specificallytailored system documentation. This allows domain expertsto control the information passed onto the user, whilst al-lowing an automated update of the data contained in thedocument based on system models.

In this paper we present the scenarios from which we de-rive the requirements and describe the underlying systemarchitecture and its interfaces to the human and machineusers. For this we adhere to WoT practices [6] by employ-ing RESTful services that exchange semantic enhanced datalike JSON-LD. We show how different existing technologiescan be intelligently combined to create intelligent documen-tation mashups.

2. RELATED WORKIt is important to support the users in understanding thesystem they are confronted with. How a user perceives asystem is dependent on the presented information that helpsform the conceptual model in the user’s mind. This concep-tual model plays a key role in installing and using such asystem and subsequently influences the user experience [3].

A recent study in a home automation scenario evaluates howparticipants respond to generated documentation when con-fronted with a home automation system installation [11]. Inthat paper the authors, however, focused on a wizard-of-ozstudy without providing technical details as to how the doc-umentation is generated. In this paper we wish to describethe design and implementation of the concept and describehow this system can generate the installation documents.

The study also showed that users belonging to a youngergeneration mostly ignore description documents and wishto rely on their smartphone to interact with systems [11].Providing documentation in multiple modalities and at theright time on their devices may speed up the understandingof the system and improve the user experience.

Providing automated assistance in the augmented reality do-main, the augmented reality manual automatically adapts tothe user and the current state of the installation [13]. Theauthoring process is automated by using video recordings ofa physical task. However, textual descriptions which can aidin the understanding of the task need to be manually added.Using our system, a repository may be queried to supply theautomatic authoring process with additional textual docu-mentation or images based on the currently identified task.

Industrial software product lines present a similarly difficultchallenge for documentation because of their high degreeof complexity and customization. The DOPLER approachaims to support the creation of documents by using flexi-ble product line variability models [5]. The tool focuses onaggregating knowledge into the system for generation pur-poses. However, We wish to allow the composition of arbi-trary sources in the document generation process and allowfor easier changes in the domain because the system we en-vision does not rely on a unified model.

Model-driven documentation tools like EMFDoc1 can be

1DevBoost EMFDoc, http://reuseware.org/index.php/

used to add documentation to software models. Each modelelement in a referenced XMI file can be annotated with acomment, which is automatically added as GenModel anno-tation. In addition, EMFDoc computes the coverage of thedocumentation and shows the results in the outline view.

In the quest for the web of things, researchers have alreadyintegrated semantic technologies within IoT applications [9].By using ClickScript2 the users can customize their applica-tions to their liking. The document generation system en-visioned in this paper benefits from these advances as moreand more resources can be queried semantically out of thebox without the need for adapters.

In accordance to the vision of creating a mashable worldwide web of things [7], a documentation generation systemthat combines several data sources using semantic technolo-gies seems a natural step towards a unified experience.

Web technologies have gained versatility in the last years.Maintaining server side code and sending it to the clientas needed, adds great flexibility to standalone HTML5 webpages. Incorporating existing template engines and semanticweb libraries is thus achievable using for example Node.js3

in combination with libraries such as Browserify4.

3. USE CASES3.1 Configurable ThingsTo illustrate the problem of creating documentation for areconfigurable things based on state of the art model drivenconfiguration technology, we look at a simple Bike config-urator demo by Configit5. This configurator allows for thedefinition of millions of bike variants and acts as representa-tive for high variability industrial products we want to dealwith [12].

… …

Figure 2: From the online configurator to the differ-ent variants of a bike and the documentation typesaccompanying each of them.

A product, the bike, requires several types documents, eachfocused on different aspects tailored to the specific variantthey describe (see 2). The technical sheet for a bike usu-ally contains the description of the individual parts of thebike, one after the other. A component may have different

2ClickScript, http://clickscript.ch3Node.js, http://www.nodejs.org/4Browserify, http://browserify.org/5Bike Shop, http://demo.configit.com/BikeShop2/Default.aspx

parameters or attributes that also need to have attached ex-planations. A brochure on the other hand, may contain textmore suited for marketing purposes. The manual may con-tain assembly or maintenance instructions along the partsof the information from the aforementioned documents. Al-though each of these documentation types describe the sameproduct, large parts of the contents may vary, while someare reused. Handling the composition in an automated man-ner allows the inclusion of content management systems thatcan handle text administration in an organized manner.

While all parts and the structure should be included in thedocumentation depending on the situation, mentioning nonexistent parts of a bike may confuse and decrease the userexperience of the product. Furthermore, a bike may be soldin different countries with different preferences. In this case,not only the language of the documentation varies, but alsothe technical configuration, and the cultural background andcontext of use.

Often small configuration changes, may entail differences instructure that are known to the expert assembling the bike.Depending on preferences, different frame parts might holdthe cables. This way documentation shows its importancewhen the usefulness of a thing is assessed by a user. Usersmight find aspects that they do or not like in a certain model.Furthermore, documentation can aid the domain expert inthe discovery of such inconsistencies. Quality documenta-tion is a good indicator for the usability of the thing itself.

Given the simple requirements derived from this scenarioand the large variant space one can easily see that manualcreation of product specific documents is not feasible in sucha situation. Even if the number of variants is small, man-ually creating documents for one such variant still remainsan error prone and time intensive task. Therefore, in practi-cal scenarios customers are usually provided with a genericdocumentation6. From the perspective of the user, genericdocumentation can be time consuming to read and it maycause confusion because of inconsistencies with the productat hand, thus hindering the comprehension of the system.

3.2 Configurable Internet of ThingsWhile the bike shop example shows some basic problemsthat we have to solve for the documentation of things, inan Internet of Things we want to cover complex systemscomprised of a variety of products. Rather than looking ata monolithic reconfigurable thing, we are looking at mashupsof (preconfigured) things to downloadable application. Oneof our target use cases is situated in the domain of homeautomation [11].

In the mentioned use case, the openHAB7 framework is usedby the authors to facilitate the device interoperation. It isan integrating middleware that provides device interconnec-tivity and the possibility to specify behavioural rules acrossa multitude of devices. A developer provides, via app store,the logic in form of openHAB rule models and a templatedescribing his application. When writing the template we

6The interconnected car Opel Adam is one of few customiz-able products which ships with personalized documentation,http://www.opel.com/microsite/adam/7OpenHAB, http://www.openhab.org

supply an editor to the domain expert that can tap into thecode model and provide content assistance.

Document Generation

Model Augmentation

Instant Help Contextual Documentation

Home Automation App Store

Device Bindings

Text  Store  

Text  Store  

Template

Code  Model  

User

Developer

Manufacturer

Figure 3: Home automation scenario where docu-mentation is provided by developers and manufac-turers alike, while the users receives only the rele-vant parts.

In this scenario different manufacturers may annotate thingswith tags that the app creators can use in documentationtemplates. E.g. using a thing as light sensor will trigger theinclusion or linking of the text describing the light sensorfunctionality. The users is burdened with making same ofit all, especially when being confronted with heterogeneouscomponents, as seen in figure 4. Adapted documentationcan improve the identification and composition of the thingsforming the system.

An app download from the store provides templates andaugments the openHAB models (see figure 3). The devicemanufacturers can add textual descriptions of arbitrary de-tail to a text store. The text store can provide the data asanswers to semantic queries. Furthermore, the current statecan be queried from the openHAB runtime models.

Figure 4: Packaged devices as they are delivered to acustomers doorstep after buying them from differentmanufacturers.

As openHAB relies on EMF technology, the textual descrip-tions of the model elements can be managed on the sametechnological level using EMFDoc. This base documenta-tion may then be uploaded to a text store to facilitate trans-lations or variations for different documentation types.

Not only can the app developers provide documentation forthe users, but the openHAB developers themselves can pro-vide documentation for the developers using the framework,either in form of standalone documents or by providing in-stant help, say as JavaDoc snippet or contextual help whiledeveloping their apps within the openHAB designer.

Like the Configit configurator the system is model based.Device and rule management are based on the Eclipse Mod-eling Framework (EMF). OpenHAB can interface with de-vices via bindings to bridge the gap between proprietaryprotocols and executes the model within its OSGi runtime,thus integrating the smart devices on the technical level. Wewish to augment this integration by providing the user withunified documentation adapted to his or her use case.

4. DESIGN AND IMPLEMENTATIONThe goal of our document generation architecture was tocreate a reusable system that integrates with both use casesmentioned and their underlying model driven developmentschemes. Furthermore, we want to enable the use of existingheterogeneous information to create documentation. As thedocumentation is a mashup of textual descriptions linked tothe underlying system model it is possible to provide instanthelp documentation snippets to be used in digital interfacesuch as augmented reality or smartphone and tablet basedapplications, as well as integration with IDEs to providedevelopment assistance.

The second goal is to integrate with a heterogeneous web-based infrastructure. E.g. to handle internationalizationchallenges and different use cases for product documenta-tion, we want to be able to connect to text storage similarlike a content management systems and wikis. This allowshandling fragmented textual descriptions for components.Text block inclusion in the documentation is filter based us-ing meta-data tags added during the authoring of the texts.

Beyond the engineered product model this information con-tained in the product knowledge base is likely to impactthe contents of the documentation. The need for manualdocument updates immediately bring the product and itsdocumentation out of sync. Furthermore, individual usersmay find certain types of information more appropriate orrequire a different detail level to suit their needs and quali-fications.

4.1 Documentation GenerationFor the document generation to take place, several com-ponents need to provide information to the generator: thedocument structure, the style information, the text blocksand the concrete system for which the document is built.According to the model these input resources are federatedand semantically linked to obtain the final document.

In the likely event of changes to underlying system describ-ing information during the development or maintenance pro-

Live Template

Product Layer

Adapter Layer

Live Document Layer

Configuration Layer

Context  Model  

Query  Module  

Engine  

Reasoner  

Document  Template  

Listener  

Queries

Configura<on  Wizard  

Base  Template   Document Engineer

THINGS

Notifications

Figure 5: Architecture overview including datasources.

cess, all documents listening to these sources will be notifiedand a re-rendering of the template takes place.

A typical software product has a knowledge base consistingof several resources which we will further call source models.These source models are the basis onto which the product istcreated. These source models can be anything ranging fromUML Models or custom models and meta models to Excelspreadsheets and property files containing product specificinformation (see figure 5).

To combine the data from the different source models weplan on using semantic web technologies such as JSON-LD,OWL and SPARQL, even allowing the integration of reason-ing technologies. SPARQL endpoints for each type of sourcemodel in the description of the product answer the queriessent from the “smart” template. By decoupling the transla-tion of model data from for each source, instead of having ageneric store, we allow independent changes or addition tothe source models.

To handle the semantic context inside our web applicationsafter it has been queried, we use JSON-LD8. This entailshigh flexibility in terms of programming support and com-bined with HTML5, the possibility arises to incorporatecomplex logic into standalone web pages (such as intelligenthelp sites for product features). SPARQL’s [15] ability toquery semantic stores via REST endpoints and the built inmechanism to filter searches make it a good option to querybigger semantic stores [14].

In addition to the use of existing models and federated in-formation we create a context model. The context modelthat is currently created manually within the documenta-tion component and contains meta-data used to adapt the

8JSON for Linked Data, http://json-ld.org/

generated documentation not only to the specific variant ofthe product but also to the current user or other externalcontext information.

The federated source models provide up-to-date informa-tion if they are alive during the execution. This is the casewith the openHAB framework, where updates to the mod-els change the execution environment. This is an especiallyuseful feature of the framework that allows truly live doc-umentation to be generated, which reflects the state of thesystem at the time of reading.

The SPARQL endpoints for the source models are declaredin the product specific part of the documentation, as theyare a direct declaration of the data sources the product ismade of which need to be incorporated into the automat-ically generated documentation. The federated knowledgecontained in these models is valuable for helping the usercreate a better mental model. Through integration it ispossible for a documentation developer to create a singlepersonalized narrative of the product.

4.2 The Model BridgeWhile relying on existing components for most parts, weare implementing a light-weight java-script document gen-eration framework. Using rendr 9 lets us render both staticand dynamic documentation on a server as well as in a webbrowser based on a strict model-view-controller principle.

As described above the model is made up solely by web end-points that are combined based on a HATEOS10 principleusing JSON-LD. In our authoring workflow we are currentlyonly supporting the linking of models in the web-browsersbut also plan on supporting link-discovery frameworks (likeLDIF11) as well as server-side reasoning (via OWL and/orSPIN rules) using user defined semantics.

The core of our specific implementation of the architecturecomprises a model bridge for the application models insidethe eclipse framework. For this we are including a light-weight web-server as Eclipse plugin that exposes the EMFmodels as linked data. Our current implementation is basedon the EMFTriple12 and the Fuseki Webserver from theApache Jena Project 13 incorporating a Pellet reasoner 14.The documentation fragments we are currently handling in-side of drupal via its ARC215 based RDF Endpoint.

Using this simple set of technologies we were able to imple-ment a proof of concept for both use cases. However, the setof components provides a basis for more advanced use. Thissetup in particular allows the system to be used to imple-ment context-sensitive HTML5 help inside the OpenHABframework acknowledges the usage context of a thing insidea complex workflow from a single id. The architecture isfurther flexible enough to generate other kinds of documen-

9rendr, https://github.com/rendrjs10Hypermedia as the Engine of Application State11LDAP Data Interchange Format12EMFTriple, https://github.com/ghillairet/emftriple13Apache JENA, http://jena.apache.org14Pellet, http://clarkparsia.com/pellet/15Drupal ARC2 SPARQL,https://www.drupal.org/node/2028111

tation. In order to generate documentation that allows forfurther manual editing (no, we are not perfect yet), we areusing Pandoc16 to generate formats such as word documents.

Figure 6 shows some static standard documentation and itsgenerated counterpart in comparison. The documentationon the right exclusively contains information blocks relevantfor a thing as light sensor (highlighted in red). Leaving outunused features of multi purpose devices greatly reduces thesize of the documentation making it more concise.

Figure 6: Standard documentation (left) and thegenerated documentation (right) compared.

5. DISCUSSIONIn our research and implementations we have only consid-ered the generation systems as well as the end-user interfaceto configuration and documentation while making assump-tions about the authoring process. For a system to scaleespecially those parts still need to be addressed.

Other research shows that it is possible to generate naturallanguage text directly from from system models like UMLDiagrams, to provide non-technical users access to the con-tained information [10, 4]. While these approaches do notfocus on generating documents, they can provide valuabledata sources for the document generation process describedin this paper and allow fully automatically document gener-ation without human text authoring.

Explicitly managing the textual descriptions of the systemcomponents allows external agencies to access the textualdata easily, in an organized manner to proof read or trans-late it, providing implicit versioning support and consistencychecks. This can also foster the collaboration among devel-opers, marketers and other contributors, allowing a separa-tion of concerns during the documentation development.

Documentation creation in enterprise environments requiresthe adoption of documentation standards. Implementingstandards like the IEEE Software Documentation Standard[1] requires tedious manual work if no automated infrastruc-ture exists. Additionally, techniques such as structured writ-ing can be more easily integrated into the documentationdevelopment cycle [8].

16Pandoc, http://johnmacfarlane.net/pandoc/

6. CONCLUSIONIn this paper we presented a system concept for the gener-ation of product specific documentation that is applicableto physical and non-physical system families. By allowing adata mashup with a unified semantic web querying interfacebetween the diverse source models a product may have, weenable contextual documentation generation.

As the documentation is generated from the underlying sys-tem models, it follows naturally that a future version of willallow for two way synchronisation enabling running softwaremodifications by altering presented documents. As a results,user-to-system dialogue becomes possible.

When implementing feature requests, developers usually cre-ate or modify parts that are visible to the customers. Pro-viding instantaneously generated documentation adds yetanother feedback loop in the development process. Thisfeedback loop is not only meant for developers or technicalpersonell, but can be used by arbitrary stakeholders. Man-agers, marketers and sales people can receive instant updateswhen the code is committed to the central repository andare able to provide valuable input to the development team,preventing costly changes later in the product cycle.

But as with all new concepts and tools, real world usage mayvary. Nevertheless, having a higher quality documentationthat corresponds to what the customer can use effectivelyis an added benefit worthwhile and relieves employees ofrepetitive error prone tasks.

We believe that many applications can benefit from sucha system as it is accompanying rather than intrusive withregard to the development process and provides a feedbackon the state of the system after changes take place.

7. ACKNOWLEDGMENTSThis work was partially funded by the German Federal Min-istry of Education and Research (BMBF) as part of the In-staGuide project (grant number 01IS12051).

8. REFERENCES[1] IEEE SA - 26514-2010 - IEEE Standard for Adoption

of ISO/IEC 26514:2008 Systems and SoftwareEngineering–Requirements for Designers andDevelopers of User Documentation.

[2] S. Antifakos, F. Michahelles, and B. Schiele. ProactiveInstructions for Furniture Assembly. In Proceedings ofthe 4th international conference on UbiquitousComputing, UbiComp ’02, London, UK, UK, 2002.Springer-Verlag.

[3] C. Beckmann, S. Consolvo, and A. LaMarca. SomeAssembly Required: Supporting End-User SensorInstallation in Domestic Ubiquitous ComputingEnvironments. In UbiComp 2004: UbiquitousComputing SE - 7, volume 3205 of Lecture Notes inComputer Science. Springer Berlin Heidelberg, 2004.

[4] H. k. Burden and R. Heldal. Natural languagegeneration from class diagrams. In Proceedings of the8th International Workshop on Model-DrivenEngineering, Verification and Validation - MoDeVVa,page 1, New York, New York, USA, Oct. 2011. ACM

Press.

[5] D. Dhungana, R. Rabiser, P. Grunbacher, K. Lehner,and C. Federspiel. DOPLER: an adaptable tool suitefor product line engineering. 11th InternationalSoftware Product Line Conference (SPLC 2007),pages 10–14, 2007.

[6] D. Guinard, V. Trifa, F. Mattern, and E. Wilde. Fromthe Internet of Things to the Web of Things:Resource-oriented Architecture and Best Practices. InD. Uckelmann, M. Harrison, and F. Michahelles,editors, Architecting the Internet of Things SE - 5,pages 97–129. Springer Berlin Heidelberg, 2011.

[7] D. Guinard, V. M. Trifa, and E. Wilde. Architecting amashable open world wide web of things. ETH,Department of Computer Science, 2009.

[8] R. E. Horn. Structured Writing as a Paradigm. 1998.

[9] S. Mayer and N. Inhelder. User-friendly configurationof smart environments. Pervasive Computing . . . ,pages 163–165, 2014.

[10] F. Meziane, N. Athanasakis, and S. Ananiadou.Generating Natural Language specifications fromUML class diagrams. Requir. Eng., 13(1), Jan. 2008.

[11] A. Miclaus, T. Riedel, and M. Beigl. End-UserInstallation of Heterogeneous Home AutomationSystems Using Pen and Paper Interfaces andDynamically Generated Documentation. pages 1–6.The 4th International Conference on the Internet ofThings (IoT 2014), 2014.

[12] J. Mø ller, H. Andersen, and H. Hulgaard. Productconfiguration over the internet. Proceedings of the 6thINFORMS, 2001.

[13] P. Niels. Intelligente Augmented Reality HandbucherZeigen, wie’s geht - Werkerunterstutzung fur dieFabrik der Zukunft, 2013.

[14] J. Perez, M. Arenas, and C. Gutierrez. Semantics andComplexity of SPARQL. The Semantic Web-ISWC2006, pages 30–43, 2006.

[15] E. Prud’Hommeaux, A. Seaborne, and Others.SPARQL query language for RDF. W3Crecommendation, 15, 2008.