Schneider Electric – SCADA Software Technical Writer
Case Study – SCADA Techncial Writer
Schneider Electric SE is a multinational corporation that specialises in energy management and automation solutions. I was hired to work on their ClearSCADA software solution.
ClearSCADA software is used for:
- Remote monitoring
- Remote control
- Energy management
- Alarms, building management, etc.
It is an industrial software solution, mostly used in the utilities industries (gas, water, electric, etc.). So I needed to write about sensors, automatic systems, controls, server redundancy measures, etc.
The ClearSCADA documentation project had two parts:
- Convert the existing ClearSCADA technical writing into a modern HTML5 online help
- Document the WITS (Water Industry Telemetry Standard) Dnp3 Driver.
I had worked in the ClearSCADA development team for 15 years as an employed technical writer, so was familiar with the product and much of the documentation.
Challenges with the ClearSCADA Project
The first step was to convert the existing FrameMaker files into Flare topics. I started by using Flare’s import feature, but the way it handled the many bullet lists in the content would have led to problems in the long term. The bullet lists were transferred as tables, and so didn’t respond to css li styling correctly (this was several years ago, so Flare might do a better job of it now!).
The solution to this was to use the HTML help version of the FrameMaker files instead. Those files were much closer to the HTML that was needed for the help topics. However, the existing HTML files had invalid code, and this caused Flare to freeze repeatedly. MadCap support were very helpful and the solution was to fix the code manually.
A bigger problem was the content itself. It had been created by various authors over the years, and unfortunately, some of it had been written in a linear style, so unsuitable for topics (I’d argue unsuitable for manuals too).
This mostly affected the driver documentation, and it meant some compromises had to be made for the WIITS driver. I wrote each topic to be as stand-alone as possible, but had to follow the existing structure for consistency with the documentation for the other drivers.
I was able to convert the documentation suite into MadCap Flare and deliver a new, modern HTML5 online help system.
What the Client Says…
Schneider Electric has used Craig Wright for a number of documentation projects, but the two main projects were:
Creation of DNP3 WITS user guide for the ClearSCADA DNP3 WITS driver
Craig contacted and dealt with key technical staff in the company to gain a thorough understanding of the WITS driver and what was required for the guide. Craig then designed the structure that the document should follow and added the content required. During the process Craig confirmed that all technical details were correct with the technical staff and was happy to get on with the guide without the need for close management.
Craig would keep us informed of the progress on a regular basis and alert us to any issues that might cause a slip of the delivery date. Due to the scale of the project we had to allocate a few days extra in the plan to allow the guide to contain the right level of information. The end result was a high quality document that provides the right level of content for our users.
Conversion of documentation from legacy tool set to Mad Cap Flare
Craig played a key part in investigating and finding the best way to convert our documentation suite from Adobe Framemaker to Mad Cap Flare. He tried out the different ways of importing the documentation into Mad Cap Flare and described the pros and cons of each approach. Craig worked closely with the other technical authors and myself during the conversion process. Craig also would contact Mad Cap support when required to deal with issues that arose during the process.
Ultimately there was no one process that allowed the documentation to be migrated without issue. So after the conversion took place Craig put a lot of effort into fixing up the Mad Cap Flare sources, a lot of the time editing the raw XHTML, to get the documentation into a stable state post import. Craig also produced notes on the Flare processes to aid other technical authors on the team. He also worked on setting up the style sheets for the look and feel of the documentation in Flare. During this whole process he also updated some of the guides to reflect updates in the product as well.
The help system for ClearSCADA now looks and feels modern and up to date, Craig’s hard work contributed to this.