Summary

Schlumberger is the world leader in oilfield services, trusted to deliver superior results and improved performance for oil and gas companies around the world. Schlumberger’s software development teams felt their tools and processes were becoming out of date, and did not lend themselves to the type of automatic content generation they required. Internally, Schlumberger were using a mix of unstructured tools, and XML tools using an older XML standard known as Docbook. They were looking for a new solution that would work across two inter-continental authoring groups – one Schlumberger team and one a partner team collaborating on development.

Key Issues

• Output formats were limited by tools and proprietary formats
• Authoring and publishing processes too closely linked
• Non-extensibility of existing tools
• Structure and format inseparable
• It was difficult for “non-writers” to update documentation
• Documentation builds had to be done manually

Solution Description

Mekon was invited in to work with Schlumberger’s software development team to transition their content authoring from an unstructured base to a topic-oriented DITA XML system. We recommended a new editor (XMetaL DITA Edition), MathML plugin (DesignScience MathFlow), and publishing tool (Antenna House XSL Formatter) to provide an end-to-end DITA creation and publishing solution that could integrate seamlessly with the existing code source control system.

At the beginning of an ongoing relationship, Mekon recommended the DITA standard, because it is the industry choice for technical documentation, and would allow Schlumberger to specialise their usage of the system as their needs became more refined. DITA’s specialisation architecture meant that as Schlumberger moved forward, enhancements to the structure of their content would not break publishing or other automatic processes later on.

After moving to a structured documentation format, Schlumberger realised that in fact running the original intended process in reverse was more efficient. By using XML documentation storage, they were able to automatically generate their XML software APIs directly from the document that described them. So instead of generating documentation from software code, they were creating software code straight from the documentation.

The system was rolled out in a dynamic and iterative fashion, with frequent interaction with Schlumberger staff. The system has been in full production for nearly a year and was presented by one of Schlumberger’s Documentation Managers at the DITA Europe conference jointly with Mekon. Industry Guru JoAnn Hackos has requested a write-up of the project for her best practices newsletter.

Features/Benefits

• Overnight automated builds through custom XSLTs and the DITA OpenToolkit
• Software and Documentation generated from a single source
• Multi-format output
• Full Equation Support and Equation reuse with MathML and DITA Conref Support
• Minimal training requirement (1 hour online walkthrough followed by one month of troubleshooting support)