Author: amdohlman

API documentation

Like many companies, Code42 has an API to facilitate integration of its data into other tools and services and allow for automation. Part of my role was to create and update API documentation for the teams I supported.

For me, this meant working closely with my SME, a developer on the team supporting Alerts, to create comprehensive, complete, correct content supporting the API commands she set up in Swagger. To create this content, I:

  • Worked closely with her to test my understanding and get any questions answered, as well as confirm any field values or critieria that needed to be included in the commands.
  • Used Terminal on my Mac to execute the commands, perfect my syntax, and verify that I received the expected responses.
  • Document each API in HTML5 according to our style guide and standards using our MindTouch/CXone authoring tool.

The resulting article is attached in PDF format, though please do forgive the formatting and artifacts as this was generated directly from the Code42 support site, which isn’t optimal.

API documentation

Code42 has since migrated this content to a new Developer’s portal, and you can also see the slightly updated content in their Manage Alerts user guide there.

“Copy to clipboard” button development

A number of Code42’s support articles contain comprehensive API command or implementation script samples, but these samples were contained in <pre></pre> blocks that were difficult for users to easily copy. We needed a less error-prone way to deliver example content to users that they could then quickly incorporate into their own tasks, workflows, and implementations.

To solve the issue, I implemented a “Copy to clipboard” button in our HTML-based support content. The full solution was multi-pronged:

  1. Use javascript to copy the example content. For simplicity, I used the open source Clipboard.js script and added it to the \media destination in our authoring tool.
  2. Write some CSS to style the new button to match the product UI, as well as a new tooltip popup to indicate to users that the content has been copied successfully.
  3. Create the HTML container to hold both the new button and the example content that we want users to be able to easily copy.
  4. Develop a bit of javascript to pass what’s being copied to the Clipboard.js script and call the tooltip popup to appear when the button is clicked.
  5. Document the whole process of adding the button to support article content in a team Confluence page so that the entire writing team can use it and add it where needed.

To see the button in action, go to the Sample uses of the Code42 API article on the Code42 support site and view any of the examples.

CSS styling

.copyBtn {
    border:none;
    outline:0;
    padding:0 5px;
    text-align:center;
    background-color:transparent;
    font-size:13px;color:#006FDE
}

.copyBtn:focus,.copyBtn:hover {
    background:rgba(30,52,142,.1);
    border-radius:6px;
    transition:all .25s ease-in
}

.copyBtn:active {
    border:2px solid #006FDE;
    border-radius:6px
}

.tooltip {
    position:absolute;
    right:0;
    cursor:pointer;
    -webkit-user-select:none;
    -moz-user-select:none;
    -ms-user-select:none;
    user-select:none
}

.tooltip .tooltiptext{
    visibility:hidden;
    width:80px;
    background-color:#555;
    color:#fff;
    font-size:10pt;
    text-align:center;
    border-radius:6px;
    padding:4px 0;
    position:absolute;
    z-index:1;
    bottom:125%;
    left:50%;
    margin-left:-40px
}

.tooltip .tooltiptext::after{
    content:"";
    position:absolute;
    top:100%;
    left:50%;
    margin-left:-5px;
    border-width:5px;
    border-style:solid;
    border-color:#555 transparent transparent
}

.tooltip .show{
    visibility:visible;
    -webkit-animation:fadeIn;
    animation:fadeIn .5s
}

.tooltip .hide{
    visibility:hidden;
    -webkit-animation:fadeOut;
    animation:fadeOut 1s
}

@-webkit-keyframes fadeIn{
    from{opacity:0}to{opacity:1}
}

@keyframes fadeIn{
    from{opacity:0}to{opacity:1}
}

@-webkit-keyframes fadeOut{
    from{opacity:1}to{opacity:0}
}

@keyframes fadeOut{
    from{opacity:1}to{opacity:0}
}

.c2c {
    padding-top:25px;
    padding-bottom:25px
}

HTML container

<div class="tooltip" onclick="tooltipMagic('PopupID')">
    <button class="copyBtn" data-clipboard-target="#Content2CopyID">
    <img height="18px" style="vertical-align:middle" width="18px" class="internal" alt="file_copy-24px.svg" loading="lazy" src="https://support.code42.com/@api/deki/files/31501/file_copy-24px.svg?revision=1&amp;size=bestfit&amp;width=18&amp;height=18" /> Copy to clipboard</button>

   <span class="tooltiptext" id="PopupID">Copied!</span></div>

   <pre class="c2c" id="Content2CopyID">Content to copy goes here</pre>

</div>

JavaScript

<script type="text/javascript">
// When the user clicks on div, open the popup

   function tooltipMagic(id) {
       var tooltip = document.getElementById(id);
       tooltip.classList.toggle("show");
       setTimeout(function(){tooltip.classList.toggle("show");},1000);
   }

   var copyBtn = new ClipboardJS(".copyBtn");
</script>

Salesforce content development

While at Code42, I supported a high-visibility project developing the new Salesforce data connection. This connection monitors an organization’s Salesforce environment for any reports that are created and downloaded from valuable sales and contact information.

Code42 is one of the few companies that have solved the problem of easily showing users when important Salesforce data has been downloaded to an external destination. So it was important that our content clearly showed that: what is needed to prepare Salesforce for the connection, how to connect it to Code42, and (most importantly) where to find this report information in the product when a download happens. To meet this goal, I collaborated closely with the connection’s development team and product owners (and set up my own Salesforce development environment) to develop and test articles on the Code42 support site. A sampling of these articles follows:

“Trusted activity” description

Code42 Incydr differs from other cybersecurity products: instead of monitoring network access points, logs, or user behavior, it tracks data files. By tracking where files go and who files are shared with, it helps users secure valuable intellectual property by responding when files are moved to unsanctioned destinations or shared with inappropriate external users.

To distinguish the allowed activity that happens naturally with collaboration from more risky exfiltration activity, Incydr applies the concept of trust: activity occurring on destinations and domains you specify is trusted while other activity is not.

However, this “trusted activity model” was difficult for sales engineers to understand and explain, especially when coupled with the nuances of cloud storage and file sharing permissions. It was a big gap causing confusion and costing sales.

To bridge this gap, I worked closely with two product owners to more clearly define and explain how Incydr’s trust works and how it is applied, and identify visuals that could really cement the concepts for users. After a number of meetings, rewrites, and reorganizations, we were able to distill down the concepts and concretely apply them to the different types of file activity sales engineers saw in every demo and implementation. The result? These two articles on the Code42 support site:

HTML justification

At The Hartford, business user procedures were written in Microsoft Word and published to the central library in .PDF. Although accessed through a web browser, the .PDFs took a significant amount of time to open on the user’s machine, a delay that is critical for call center users (whose performance is measured by a number of time-dependent metrics). In addition, links between documents didn’t work as well as they could, and using Word didn’t scale for future document development.

Before my team could switch to authoring in HTML, however, we had to justify to senior management the purchase of Dreamweaver, our chosen development tool, as well as detail the benefits we’d achieve by switching from Word to HTML. With input from my team, I created this SARIE (situation-alternatives-recommendation-implementation-evaluation) document that described these benefits and the reasoning behind our selection of Dreamweaver.

HTML SARIE justification

By providing this full justification, we proved that we’d completely researched the situation and management approved our purchase. We switched to authoring all new content in HTML, giving us the flexibility and scalability we need for future development as well as decreasing document load times and increasing ease-of-use for our business users.

LightGuide software manual

LasX Industries’ LightGuide laser control software provides a fully-featured application for the management of laser manufacturing production jobs. Each time I revised a software manual, I saw much more restructuring needed that simply couldn’t be accommodated in basic FrameMaker book and chapter files. This challenge wasn’t helped by user interfaces that differed between two hardware platforms.

Similar to the LasX laser system hardware guides, authoring XML-based topic files in the DITA architecture permitted me to take advantage of the efficiencies of content reuse. By using attribute values intelligently, I could create the structure to support two different outlines for the graphical interfaces without adding overhead. And by generating online HTML help directly through the DITA-OT expanded delivery options from simple print and PDF for more direct, on-point user access.

LightGuide Software manual excerpt

Developed with FrameMaker 9.0 running the DITA-OT plug-in. Delivered in print, .PDF, and HTML Help.

Laser system hardware guide

At LasX Industries, hardware manuals for each laser system were generated in a manual process: I worked with the project engineers to determine which system was most similar to the new system being assembled, tracked down the source files for that system, then cut and pasted the old material into new chapters and updated it as needed. While this system preserved audit trails for older system guides, it was error-prone and difficult to maintain.

Because components were largely common among differing systems, switching to an XML-based, DITA compliant authoring method was a clear solution. I started a new content library from legacy guides, rewriting and restructuring information into topic files organized into larger ditamaps. Since all guides were delivered as PDFs, I chose to remain within the FrameMaker-based authoring environment and revised template files as needed to retain look and feel. And as a team of one, I deliberately kept specialization to a minimum for maximum flexibility and ease-of-use.

Laser system manual sample

Developed with FrameMaker running the DITA-OT plug in. Delivered in print, PDF, and HTML Help.

IRAdirect system documentation

One of my early assignments as a consultant involved documenting a complex IRA management system. Because a large number of developers working on this system were also consultants, project managers feared losing that knowledge as consultants rolled off the project and also needed a quick way to bring new developers up to speed.

A large part of my work on the project involved documenting the various components that comprised this system and how they worked together. This sample describes the reporting engine for this system and ensured knowledge transfer as well as saving billing hours by giving new developers the ability to build their own groundwork without needing full-time assistance from more experienced consultants.

Developed in Word. As I only have hardcopies of this document, I’ve scanned this sample, so please forgive the quality.

IRAdirect system documentation sample

Code42 content restructure

The “Data Connections” section of Code42’s support site had a problem: While it contained excellent, comprehensive content, each of its 10 or so articles were exceptionally lengthy. This meant users missed important steps or tips while endlessly scrolling to find the pertinent nugget that would help them solve their issue.

Content restructure inventory & planning

To break all this content down into smaller, more easily digestible topics, I first used the digital whiteboard application Mural to take stock of what we had. This inventory shows the existing articles (outlined in black) with the eventual new articles that would be created as we broke out that content.

The result was a revised introductory article: it first gives users a starting point for planning their connection, then serves as a landing page to dozens of new, bite-sized articles that target specific topic to best serve user needs. Go to Introduction to adding data connections on the Code42 support site to see the new, more effective structure and content.