Director, Global Technical Service Information
Company Name: Ericsson
Name of Submitter: Sharon Figueira
Email Address: firstname.lastname@example.org
The Ericsson Bangalore Technical Publications team embarked on an initiative to simplify the process of documenting the Managing Information Base (MIB ) reference help. The existing process of documenting the MIB reference help was tedious and time consuming. It involved developing MIB reference content manually using the engineering specifications. The entire documentation cycle required huge efforts in terms of time and resources. In addition, this process required maintenance of multiple documents in the content management system. The manual extraction of information mandated review efforts by the SME as well as test efforts by the team to ensure that the quality was up to the mark.
We came up with a process to extract the reference content dynamically from the source MIB files. This source is verified and also validated during the software development life cycle (SDLC). This ensured accuracy and quality of the end-user reference help. Applying XSLT and CSS to the extracted content, we were able to process it and even format it. We could process multiple MIB files at one go using batch processing. Extracting content from the engineering source files ensured technical completeness; using XSLT resulted in good quality output. Also, the need for maintaining the documentation files is nullified resulting in zero maintenance cost.
The data below depicts the comparison between the legacy process and the new process. Please refer the attached file to view this data in table format.
Legacy process: 640 person hours (involving multiple resources ) per release for 50 MIB files New process: 4 person hours (typically by one resource) per release for 50 MIB files
Legacy process: Content had to be maintained in the content management system New process: Fresh content is generated for every release automatically from the source files; hence no maintenance of content is required
Legacy process: Data extracted manually from engineering specifications, hence prone to errors New process: Data extraction from MIB source files, handled by XSLT, hence good quality output achieved
Legacy process: Help topics created in the authoring tool New process: Dynamically generated topics can be published as stand-alone help or imported in to the authoring tool to be published along with other topics
2. Customer Focus:
The inflow of support tickets and queries related to the MIBs reference help had increased manifold. The customer support team found it difficult to handle the enormous number of queries on a regular basis using the legacy process as it involved tracking the MIB information manually. These customer queries were often redirected to the Technical Publications team. Maintaining up-to-date information and providing the required information to the end-user in a user-friendly format had become a challenge. This also consumed time in terms of cycles of communication between customer, customer support team, and Technical Publications team.
Knowing the importance of the MIB reference, it was imperative that we provided up-to-date, accurate and concise MIBs reference help to the end-user. MIB files themselves are difficult to read; they are only meant to be imported or “compiled” by a network manager. Refer to ‘Figure 1 MIB Source File’ in the attached document.
The new process of generating MIB reference help ensures that critical information such as the access type, the current status of the object, alarms (if any), and the APIs is readily available to the end user in a format that can be interpreted easily. The new dynamic help also saves additional efforts of a user navigating to multiple sections and documents to determine related details of an MIB object, as all the details related to a MIB object are grouped together. This help system provides advanced features like sort, sort based on conditions, advanced search options and DHTML effects in the help library that gives a great user experience. Refer to ‘Figure 2 Generated HTML File’ in the attached document.
This process can be used to generate HTML/XML help files from any engineering source or code base. The generated HTML/XML files can be imported seamlessly into any authoring tool that supports XML/HTML to create the desired output (HTML5, Webhelp, HMTL, DITA), in addition to any other existing content. The generated files can also be published directly as standalone help using free tools such as HTML workshop. Some examples where this process can be applied are: API reference, Commands reference, Alarms reference, Known issues and workarounds for release notes; the list is endless. A basic knowledge of XML, XSLT and CSS is required to implement this process.
This process does not require any specific tool. Using any scripting language (Perl for example), we can extract information, process it using XSLT, and run a batch file to generate multiple files in one go. Any free source code editor (like Notepad++) can be used to create the Perl/XSLT/Batch file. Therefore, it is cost efficient too. One need not worry about the huge number of files that need to be handled. Multiple files can be handled at one go using batch processing. Creating a batch file is a one-time activity. Maintenance of the Perl and XSLT scripts is easy as these scripts are small and simple.
A support ticket logged by a customer towards resolution of any MIB reference issue typically spanned across 2 to 3 weeks as this involved multiple levels of scanning and analysis, after which it was redirected to the Technical Publications team. With the new process in place, not only the time to resolve the support query is reduced to about 2-3 days, but the number of MIB reference information related queries also has also been reduced immensely. This can be attributed to the fact that the new process MIB reference help uses content from an already verified and validated engineering source.
The generation of reference help can conveniently be taken up late in the release as the entire process can be completed in matter of a few hours. Unlike other documentation cycles that require review and test cycles for qulaity, this process is a one time activity that ensures completeness and accuracy.
5. Transformational Value:
The management was highly appreciative of the pilot project demonstrating the dynamic generation of MIBs reference help. Necessary approvals were obtained from the stake holders to set the process and define a new way of work. The team was encouraged to determine if this process could be extended and replicated to other areas like the Alarms reference, Events and Notifications reference. The management also encouraged the team to submit this as a proposal at the CIDM Best Practices conference.
The dynamic generation of MIB reference help emerged as a foolproof method to tackle the existing problem in the legacy process of sourcing the reference information. The efforts and time saved by simplifying this process could be channelized for other priority tasks. The management consciously identified the legacy process as a hurdle that required immediate attention and a change in the way of working. This was vital as the time taken for this process and efforts spent were directly proportional to the operational costs. A research study was triggered to determine alternative processes and a team was set up to pilot the dynamic generation of MIB reference help in an internal hackathon. Inputs from various stake holders such as the engineering team, the build management team, and the information architect were obtained. Persistent coordination efforts by the management ensured that the pilot was completed on time. The pilot was a huge success and the approvals from the stake holders initiated the process change.