| Information Modeling for Document Management: the Key to Successful System Selection and Deployment | Table of contents | Indexes | Keep it simple - Interactive electronic applications with SGML | |||
| Leenheer Paula |
| Mackenzie Colin |
Ajaib - A Case Study Of An SGML/Intranet Development |
(Getting Documentation Off The Shelf) |
| Paula Leenheer |
| Colin Mackenzie |
Abstract: |
| Mackenzie |
| This paper will be presented at SGML Europe 97 as an informal discussion between the developer and the customer reflecting the dialogue and key decisions made during the Ajaib project. This presentation will illustrate the partnership required in complex projects to successfully design, implement, and deliver quality solutions. Demonstrations of the resulting system will be available at the conference. |
Background |
| Brunei Shell Petroleum (BSP) / Shell International Exploration and Production (SIEP) considered the role of documentation within an oil production environment. BSP aspires to increase the safety and performance of existing assets (equipment) through adequate, "fit for purpose" information, as is typically contained in documentation. Unfortunately (as is common with most stagnant, hard copy based documentation), operators had found that the existing documentation was out-of-date, difficult to understand (BSP have many different native languages), and did not provide them with all of the information they needed to perform their day-to-day activities. This situation resulted in the existing documentation being left on the shelf. BSP/SIEP decided to design a system that would bring documentation off the shelf and into the day-to-day activities of the operators. |
The Challenge (Delivery minus 6 months) |
| BSP decided that the core information for the system should utilise SGML to manage the various information content types and relationships. BSP chose to re-use DTDs specifically developed for Shell Expro to capture the information. This information consisted of asset information (e.g., equipment descriptions for specific platforms, pipelines and systems), organisation information (e.g., description of BSP personnel and their responsibilities), and activity information (e.g., descriptions of maintenance tasks that operators perform each day). Furthermore, the system should also contain additional explanatory information, as is usually contained in training manuals. |
| The new system had to provide all the information that operators require from a single point of delivery, in a format that would be appealing to the operators. The decision was made to use Web technology and standard products to deliver the specially created content in a textual and graphical form. The textual information would be converted from SGML to HTML prior to delivery of the final system. |
| BSP decided that Simplified English should be used to ensure that the content created for the project would meet the requirements for being easily understood by end-users whose first language was not English. |
| How could BSP assess whether or not the successful use of documentation could indeed increase the performance of their business? This would be achieved by designing the system to be interactive to allow the operator to enter equipment readings and display the performance of their assets over a given timeframe. |
| The system would initially be used to support the three Glycol Regeneration Units on the offshore Champion-7 platform. Delivery was required in 6 months time to address issues highlighted in a previous internal audit. |
| The system was to be called Ajaib (Malay for miracle). |
The Project Team (Delivery minus 5 months) |
| BSP created the Ajaib project team enlisting SIEP as technical documentation specialist, DPSL as system designers and developers, and ODL as technical authors. The project team was geographically remote for most of the life of the project, with bases in Brunei, Holland, England, and Scotland. E-mail proved to be an essential tool allowing the transfer of files, prototypes, but most importantly, ideas between members of the project team. |
Initial System Design (Delivery minus 4 months) |
| The project team met to consider how best to create a system to fulfil all of the project requirements. It was decided to utilise the BSP Corporate Management System (CMS) as its structure was designed to cover all of the vital areas of BSP's business - namely organisation, activities, and assets. |
|
| To aid understanding, the organisation/activities/asset structure was transformed into "Who", "What", and "Where". A prototype application (see figure 2) was created using HTML, JavaScript, and the Netscape Navigator Internet browser to test the ease-of-use of the proposed system. The design involved three selection boxes (for "Who", "What", and "Where" that could be used individually or combined to select the various sections of the sample content). The prototype was sent to Brunei and created a substantial amount of support for the project. While the operators liked a lot of the ideas presented by the prototype, they found the multiple selection criteria confusing. One feature of the prototype that was particularly successful was the use of image maps for navigation. |
 |
| It was decided to extend the use of the CMS to provide the basis of a core image map that would be used to allow the user to navigate between the main information types in the system. |
 |
System Design (Delivery minus 3 months) |
| The project team worked on a data model that would accurately reflect the hierarchies within each content type (organisation, activities, assets) and the relationships between the content types (e.g., "roles" in the "organisation" may have a "responsibility" to perform a specific "activity"). This work was supported by a data gathering exercise where operators were interviewed and existing documentation and design drawings were examined. |
| A design review meeting was held involving the entire project team and a supervisor from Champion-7. The involvement of the supervisor was crucial not only to help establish end-user requirements, but also to achieve a "buy-in" from the target, key users of the system. The problem of discussion and design using three separate complex data hierarchies was solved by the use of sticky notes, marker pens, blu-tack, and thread to illustrate and instantiate the data hierarchies. Once the entire wall was covered, the data and navigational requirements had been decided! |
Content Development (Delivery minus 2 months) |
| The system's architecture and authoring environment was created. The DTDs were adapted and enhanced to capture the high-level relationships necessary for navigation in the final system. The DTDs contained special elements to allow the author to mark-up any textual content that may provide a useful link (without using "id/id refs"). This allowed the author to create rich content without having to manage the cross references. An authoring environment was built and configured allowing the technical author to key (and parse) SGML instances containing Simplified English (the authoring environment used Adept from Arbortext and Aleth CL from Erli). Graphics for the system were created in a format that could be viewed using freely available Web browser plug-ins supporting a rich array of graphical content including graphs, CAD drawings, and animation. |
 |
| The SGML content was created by the technical authors under supervision at DPSL's offices in Swindon. The close relationship between the SGML consultants and the technical authors ensured that the SGML structures were created to the quality required and that the developing system could be tested on an on-going basis. Two supervisors from Champion-7 were involved in the authoring process to ensure accuracy and to again provide end-user perspective. As the author did not have the benefit of an SGML repository (a repository component was not part of the initial system to reduce development time), a filenaming convention was developed to allow the author to easily track the various text files through the system. The graphics for the system were created at the technical authoring company headquarters in Aberdeen. The integration of the text and graphics provided some issues, specifically the lack of naming conventions for the graphics, which resulted in the rather embarrassing demotion of a platform supervisor (as his photograph appeared in the section for an operator). These issues were easily addressed prior to delivery. |
| HTML image maps were created to allow simple navigation within organisation, activities, and assets. |
 |
| In place of the standard HTML filenames, these image maps contained references to SGML elements. A program was created to take the SGML keyed by the technical author, combine it with the image maps and HTML style templates to produce a complete HTML representation of the data. The conversion program automatically created HTML with a consistent look and feel including an individually tailored table of contents for each page of information, summaries of hazards and images within each page, and a navigation section providing links within and across the content hierarchies. The conversion program also created HTML links wherever it successfully found a match for any of the special link elements created earlier (the program only created links to content that existed). |
System Development (Delivery minus 1 month) |
| Database forms, tables, and queries were developed to capture equipment readings information in the run-time system. Data would be passed to the database on the Ajaib server from the operators desk using standard Intranet technology combined with specially developed CGI programs. These programs create graphs accessible by the user from within the Ajaib system and contain links back to the HTML content to enable the user to work out how they can correct any anomalies in performance of an asset. |
 |
Delivery |
| The system was delivered and installed according to schedule. Some installation issues were highlighted, particularly the need for clear installation and configuration instructions for all of the software packages that are in Ajaib. The development of the project within the timescale was only possible by the integration of a number of standard software packages (from the Intranet server and database to the browser and all its plug-ins). BSP IT staff also had to install new hardware and software to provide the environment and communication support required (including a Microwave link from the server to the clients). BSP found that some Internet applications were immature and required more attention than was expected. |
Project Review (Delivery plus 3 months) |
| The Ajaib solution has proved a great success at BSP. The operators now have a system that is tailored to their local environment and delivers information that they understand. The clarity of information was such that SIEP (sponsored by BSP) are implementing a Simplified English lexicon that can be used for many future projects. The value of documentation linked to asset performance via the day-to -day activities of operators was accepted by the Shell Production Superintendents conference when the Ajaib system was demonstrated to attendees. |
| The Ajaib project is moving forward in a number of different ways. New content for a different equipment group is being developed and many different Shell Operating Units are considering implementing Ajaib (or Ajaib-like) systems. This expansion will require an evolution in the functionality and architecture of the Ajaib system to provide a robust re-usable system from the "mark one" Ajaib system. |
| The Ajaib system has also been demonstrated to various other bodies outside Shell to provide further feedback. Amongst various positive feedback, Defence organisations felt that the Ajaib approach could be easily adapted to suit their requirements and felt that the use of documentation to describe individuals responsibilities was innovative. |
Summary |
| The formula used in the Ajaib will be re-used to provide success in other projects. The key to the success of the project was the creation of a project team (including customer managers, developers, and end-users) with a diverse range of skills and experiences who respected each others opinions. The system has proved successful because the users can access the information they require quickly and easily, and the information provided by the system is easy to understand. |
| Information Modeling for Document Management: the Key to Successful System Selection and Deployment | Table of contents | Indexes | Keep it simple - Interactive electronic applications with SGML | |||