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:
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 and things like that.
SCADA Software Documentation Project
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.
As I had worked on the ClearSCADA documentation for many years, I knew it was created in Adobe FrameMaker, converted to .mif, and then fed into an HTML Help system via an in-house tool. I was relatively new to Flare at this time, so the prospect of importing lots of content was a bit daunting, but it proved to be a very valuable learning experience. I knew Flare supported FrameMaker imports, so I figured it would be a simple process. That wasn't quite the case!
The WITS driver was completely new to me, and although there were many different drivers covered in the documentation, I had only worked on one of them. I was warned that WITS was complex, as it overlapped with the existing Dnp3 driver.
Traditional tri-pane online help created in MadCap Flare.
Schneider Electric's SCADA software documentation used PDF, online help and mobile help outputs.
Challenges with the ClearSCADA Project
The existing ClearSCADA documentation had been written in Adobe FrameMaker, converted to .mif, and then fed into an HTML Help output via an in-house tool. I knew all this, because I'd been working on the documentation (along with other technical writers) for many years. At the time, I was new to Flare, but knew it could import directly from FrameMaker. So that was my first plan. Unfortunately, it didn't work out - the documentation had a lot of bullet points and the import process handled them by converting them into tables. I knew that would cause problems further down the line when it came to styling the bullet lists, as they weren't genuine HTML bullet lists. So instead, I took the HTML files from the HTML Help output and imported those. Much better...at first. But as I started to work with the files, Flare began to struggle, to the point where it was freezing far too often.
MadCap support were great as always, and through trial and error, we discovered that the HTML files we imported actually had invalid HTML - the bullet lists were wrong. Browsers could still display them correctly, but the code was invalid. I fixed all of the files using a mix of find and replace and manual work.
Documenting the WITS driver was a different sort of challenge. It took me a while to get to grips with the technicalities of the protocol, but the SMEs were available to guide me in the right direction. The biggest problem here wasn't understanding the material, it was getting it to be consistent with the other drivers.
I didn't know at the time, but the driver guides (with the exception of the one I had written) had been written in a linear format! So there were lots of sections that offered very little context as you were supposed to have 'read an earlier section'. Clearly, this doesn't fly with a topic-based online help, and in my opinion, doesn't work for a traditional manual either. There was no time to restructure all of the driver guides, so I had to make a compromise, where the WITS driver was as topic-based as possible, but still followed the structure of the other driver guides.
From the client, Paul New, Software Development Manager, Schneider Electric:
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
This was a new guide which was included in the main ClearSCADA help. This DNP3 WITS ClearSCADA driver is an extension to the core DNP3 driver and provides extensive functionality for the UK water distribution market. However the WITS driver is very different to most of the existing drivers in ClearSCADA, so a lot of content was completely different to any of the existing guides.
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.