Upgrade to RoboHelp 2019, then clean-up your HTML tags!

Posted on by admin

So, you decided to upgrade to RoboHelp from a previous version. Beautiful. I did, too! And it’s great!

Except for all that leftover dirty html!

I am very excited by the ability disallow in-line styling, but years of in-line styling by a wide variety of authors has left our project with some very messy html. If you find yourself in the same predicament, keep reading and I’ll show you some great ways to clean it up!

WARNING: Continue at your own risk. Make lots of backups. If you break it, it’s not my fault, I warned you. And I will continue to warn you many times throughout this document.

These instructions are really for more advanced users and you should have a fairly decent amount of HTML knowledge before you do this.

Back it up!

BACK UP EVERYTHING ALL THE TIME. Again, BACK UP EVERYTHING ALL THE TIME!

Before you do anything, please make a copy of your project. Or maybe two copies. During the process of upgrading my project from RoboHelp 2017 to the new, sleek, amazing RoboHelp 2019, I actually made a copy at several points, especially while doing mass find/replace tasks.

Since this topic isn’t really about the upgrade process so much as it’s about the clean-up of your HTML after the upgrade, I’ll just give you a brief outline of my upgrade process:

  1. Remove project from source control (and archive RH 2017 version).
  2. Make a copy of the project.
  3. Clean up the project to get it ready for upgrade (made sure all file names had no spaces, cleaned up some stuff, organized topics, things of that nature).
  4. Make a copy of the project (so I don’t have to start all over if the upgrade fails).
  5. Clean your in-line styles. This was farther down, but I realized after a lot of work that you really should do this first to avoid screwing up your COnditional Build Tags. (make a new copy of your project after every replace. If something goes wrong, you’ll be glad you did!)
  6. Upgrade the project (Make sure your RH 2019 version has all service packs before you do this, or, like me, you’ll need to go back to that copy and start again after you apply them!)
  7. Make a copy of the new project.
  8. Spend some time figuring out the new format and getting used to the new layout. It’s beautiful. Gush about it to your coworkers and anyone who will listen.
  9. Realize that all the inline styles from the project are causing things to look funky.
  10. Deep sigh because you know cleaning up the inline styles is going to take FOR-EV-ER!!
  11. Realize you have options!

Regex is my savior

You know and I know that making all of these changes in RoboHelp is going to take forever. Cleaning up HTML is a horrendous thing. And because RoboHelp now uses HTML5, I want to take advantage of that! I turned to Google for some help, and the overwhelming answer was “use a regular expression“. It took me some time to figure out how to do this, but it really is easy once you know what you’re doing, and I’m hoping to save you the trouble of trying to figure it out on your own.

Notepad++ to the rescue!

We’re going to use Notepad++ to do this cleanup, and here’s why:

  • Notepad++ allows you to use regular expressions.
  • Notepad++ allows you to filter the type of files you’re making replacements in.
  • Notepad++ allows you to make changes to an entire directory’s worth of files and sub-folders.
  • Notepad++ is free.

We’re going to use an awesome search feature in Notepad++. I actually recommend that, as you go through these, you do the find/replace one at a time for the first 10 or 15 replacements, just to make sure nothing is going wrong. I’ll list some potential roadblocks at the end of this article.

This is advanced stuff! (A disclaimer)

I’m not taking responsibility if you screw this up. I am merely telling you how to do it because I had some trouble finding an exact answer that wasn’t bent towards programmers. I had a programmer (Hi, Robert!) help me tweak the expression because I don’t know much at all about regular expressions at all. (I always say, I know enough to be dangerous…)

I’m not telling you this to keep you from trying this. No, not at all. I’m telling you this because I want you to BACK IT UP!

Back it up!

Back up your files again. I can’t stress this enough. When you find/replace all, you don’t get an undo. Really, best practice will be to make a copy of the entire directory before each mass find/replace. It’s a lot of work, but less work than, say, manually editing 800+ topics in your project to undo a find/replace that wasn’t … accurate.

Open search and set parameters!

WARNING: BE VERY, VERY CAREFUL WITH THIS, PARTICULARLY WITH THE MATCHED PAIRS. Some replacements have gone badly, requiring me to clean them up. This will happen if you don’t think your replacement through fully, and is why you should go one at a time if you aren’t sure!

Also of note, watch out for Conditional Build Tags (CBTs). Before the upgrade to RoboHelp 2019, CBTs have the special robohelp tag: <?rh-cbt_start condition=XXX” ?>. After you upgrade to RoboHelp 19, CBTs become a “class” for your html tag, so you’ll have something like <td data-condition=”CBTName”>. Because of this, it’s probably best to do your clean-up BEFORE you upgrade to RoboHelp 2019.

  1. Open Notepad++.
  2. Open search:
    • CTRL + F on your keyboard and click the Find in Files tab, or
    • Search > Find in Files….
  3. In the Find what: field, enter a phrase from the FIND EXPRESSION column in the chart below.
  4. In the Replace with: field, enter a what you want to replace the found string with (some suggestions are in the REPLACE EXPRESSION column in the chart below.
  5. In the Filters: field, enter a file type if you want to limit the find/replace option to certain file types. I strongly recommend using this option. I put *.htm in the field to limit my search to HTML files created by RoboHelp. Without a filter, it’s possible the search will find/replace something you don’t want replaced. (One of my searches had a match in a .png file, and a replace would have corrupted the image.)
  6. In the Directory: field, browse to the parent folder of the HTML files you want to perform the find/replace operation on.
  7. In the Search Mode section, click to select the Regular expression radio.

After all of this, I usually do a Find All first, then double-click a file from the find results and switch to the Replace tab. I then just do Find Next and Replace until I’m satisfied that the search is going to cover all desired instances without blowing things up. Once I’m sure of that, I switch back to the Find in Files tab and click Replace in Files.

Find/Replace suggestions

All of the examples in the chart below are real examples that I found in the project html files and the real expressions I used to get it cleaned up.

Dirty HTML
example		Clean HTML
example		FIND
EXPRESSION		REPLACE
EXPRESSION		Notes
<td style=”text-align: center;”>

<td (anythingatall)>		<td>
Option 1: <td style=”text-align: center;”>

Option 2: <td (.*?)>		<td>Fairly common in-line styles, centering the contents of a table cell. Because the open/close tag will remain the same, this find/replace shouldn’t pose many problems.

After upgrade to RH19, use the first option (find/replace exact strings, use Notepad++’s strong search feature to do a search ONLY for option two, then weed through the results to find individual tags you need to remove).

If before upgrade to RH19, you should be safe to use option 2. In Option 2, the (.*?) is essentially a wildcard that finds all tags with any inline style. It should break safely across lines, but, as usual, preview your search results before you do the replace all.

You can extrapolate this search/replace out for any in-line styles for any html tag with in-line styles that you want to keep the base tag for. You’ll still want your <td> tags, your <p> tags, your <li> tags, etc… but you probably won’t want to keep any styles associated with them, so this is an efficient way of cleaning those up.
<span style=”font-style: italic;”>
<em>Italicized Content</em><span style=”font-style: italic;”>((.*?))</span><em>$1</em>Replace text formatted as italic using a <span> tagwith the same text wrapped in an <em> tag instead.

In the find expression, ((.*?)) finds matched tags breaking across lines with any content between the tags, and the extra parens around the expression means that you want to preserve the text.
In the replace expression, the $1 tells Notepad++ to take the preserved content and insert it here in the replacement string.
<span style=”font-style: bold;”>
<strong>Bold Content</strong>
<span style=”font-style: bold;”>((.*?))</span>
<strong>$1</strong>
Replace text formatted as bold using a <span> tagwith the same text wrapped in an <strong> tag instead.

<span>Content that has no formatting</span> 		Just content, no tags.


<span>((.*?))</span>
$1
Find all unformatted text wrapped in a <span> tag and remove that tag while keeping the content.
<li><p>List item content.</p></li><li>List item content.</li><li><p>((.*?))</p></li><li>$1</li>Removes <p> tags from inside list item tags.

I really don’t understand why RoboHelp wants to put a paragraph tag on everything. In my personal opinion, it doesn’t belong inside of list items, table cells, or in many of the other places that RoboHelp likes to put it in, and they perpetuated that issue into RH19 (though there’s some feature requests asking them to stop, I’ll let you know if they do!). I like my HTML clean, and I think list styles have enough to deal with competing with the ol and ul tags without throwing the paragraph tag in the mix.

Replace all the li instances on both the find and replace with a td and you can clean up paragraph tags inside of table cells, but be careful, some table cells might have more than one paragraph inside them, in which case, manual removal is necessary.

Good luck!

Please add a comment if you think of any more helpful examples of using RegEx to clean up old RoboHelp html before you upgrade to RH19! Again, read all the warnings, and back up everything!

Fake Memes – The Oxford Comma!

Posted on by admin

I recently did a presentation at work that included talk about the Oxford Comma. In the presentation, I included some memes to make the presentation a little bit funny, and because funny helps people learn.

In my quest for memes I came across this… thing:

Oxford Comma Meme "We invited the Church Representative, Raymond Teller and Penn Jillette." with a picture of penn and teller.
Oxford Comma Misconceptions

Let’s talk about this meme. This is just WRONG.

First, the phrase “church representative” does not need to be capitalized. People love to capitalize random things, but if you’re going to make a grammar meme, you should totally do it right, don’t you think?

Now, let’s get to the meat of the theme, the use of the Oxford Comma. In no way, shape, or form is this meme a good example of when to use the Oxford Comma (OC), nor is it a good example of why one should not use the OC. The “church representative” is not one of the “things” in the list, so this list does not consist of a serial list, which is three or more items. Here’s the

Ox·ford com·ma
noun
a comma used after the penultimate item in a list of three or more items, before ‘and’ or ‘or’ (e.g. an Italian painter, sculptor, and architect ).
Let’s look at the first sentence in the meme:
We invited the Church Representative, Raymond Teller and Penn Jillette.
Since “Church Representative” is not a proper noun, let’s take it lower case:
We invited the church representative, Raymond Teller and Penn Jillette.
Now let’s talk about the items in the imaginary “list”. In the scenario, Raymond Teller and Penn Jillette are both church representatives. Both. Two. Plural. Here’s the second place where the author of this meme goes wrong in assuming that an Oxford Comma is a valid option. Here’s how the sentence should read:
We invited the church representatives, Raymond Teller and Penn Jillette.
There are two representatives, and they did not pluralize the word that describes Mr. Teller and Mr. Jillette.
To summarize, the list only consists of TWO items, Raymond Teller and Penn Jillette. The comma in the sentence serves to indicate that you are starting a list of the representatives, but without that s in representatives, you don’t really know that.
Aside from that point, Mr. Teller and Mr. Jillette are known professionally as “Penn and Teller”, and the sentence puts them in a different order, which kind of hurts my brain, so I’ll make one more change to the sentence:
We invited the church representatives, Penn Jillette and Raymond Teller. 
There. That’s so much better! Now we must delete the meme from the Interwebz!
If you’re going to start a meme, you really should know what you’re talking about. Also, I very much doubt that Penn Jillette will never be a church representative.

Teller knows how to laugh

Pretty print in RoboHelp

Posted on by admin

I spent a little bit of time trolling around trying to figure out how to use a pretty print-type add-in in RoboHelp. I had a lot of trouble with this, primarily because RoboHelp would de-register the baggage or totally ignore the second style sheet (and delete references to it from topics!
After a lot of playing around during a recent custom responsive layout build, I finally found a product and setup that works. It does require a bit of finessing, but if you’re savvy, you should be able to get it to work!

My environment

I haven’t tested this setup in every version of RoboHelp or in any other scenarios. That said, it should work in other versions. If your setup is different, post your results in the comments and let me know how it worked for you!

This is my current authoring setup:

  • RoboHelp 2017, R2
  • Windows 10, 64-bit
  • svg, two workstations and one build machine
  • highlight.js, v.9.12.0, download version, custom package.

Setup

  1. Visit highlight.js.
  2. Click the Get version 9.12.0 button (new versions will change this button name, please just click the button no matter the number!).
  3. On the Getting highlight.js screen, scroll down to the Custom package section. Click to select or de-select the code types you need to pretty-print. Be liberal, if you think you might need it in the future, click it. The package isn’t huge. 🙂
  4. Click Download.
  5. Locate the downloaded file hightlight.zip and extract the contents.
  6. Open the extracted highlight file.
  7. Copy the highlight.pack.js file to your clipboard.
  8. In your RoboHelp project, create a folder called js in Project Files.
  9. Right-click your new js file and select Explore….
  10. In the js folder in Windows explorer, paste the previously copied highlight.pack.js file.
  11. Back in RoboHelp, right-click the js folder, select Import Baggage, then click File.
  12. Double-click the highlight.pack.js file.
  13. Return to the highlight.js web site.
  14. Browse through the different languages and styles (click the links under the code block) until you find a style that you like, making note of the style name.
  15. Return to the opened highlight folder and double-click the styles folder.
  16. Locate the .css file that corresponds to the name of the style that you want to use and open it in Notepad or Notepad++ (or your own preferred text editor).
  17. Copy the entire contents of the file to your clipboard.
  18. Back in RoboHelp again, locate your project style sheet (generally default.css, but yours may be named differently). Check out the file, if necessary, and open it in your text editor (right-click>Explore, double-click or double-click if your file associations are set in RoboHelp. DO NOT edit it with RoboHelp’s stylesheet editor).
  19. Go to the end of your default.css and paste the contents of the highlight.js stylesheet in your style sheet.
  20. Save your changes.

Whew! Now you have highlight.js installed, how do you actually use it in topics?

You will need two blocks of code, inserted in the html of your topics, to make a code sample pretty:

This first block of code you will paste in your topic head, just before the </head> tag :

<script src=”../js/highlight.pack.js” type=”text/javascript”></script>
<script type=”text/javascript”>//<![CDATA[
hljs.initHighlightingOnLoad();
//]]></script>

IMPORTANT: Make sure that the path to the package, ../js/highlight.pack.js, matches the path to the default.css file in respect to the path. Your topic may be several layers deep relative to the css and js files, the path should reflect that. For example, if the topic’s path to the stylesheet is ../../../default.css, then the path to the js file should be ../../../js/highlight.pack.js. In other words, make sure that the number of ../ sequences before the js/highlight.pack.js is the same number of ../ sequences before the default.css.

The second block is pasted in the html in the position that you want to insert your code sample:

<pre><code></code></pre>

Paste the code after the <code> tag and before the </code> tag!

Here’s what your code will look like, these two code blocks are highlighted in yellow:

HTML representation of the code blocks mentioned in the article.
Topic HTML

Templates (.htt files)

You can add the first code block to a topic template, but it only works if the template is used on topic creation. If you add the code block to the .htt file, it will only work on new files created from that template. You will still have to place the script in the html heading manually for topics that have already been created.

Code sample prep

Before you paste your code sample inside of the second set of tags, you need to do a little bit of prep work so that it actually works properly when you paste it in. I find that Notepad++ is the best tool for doing this. It’s free, and the tasks listed use steps from that program.

  1. Open Notepad++ and paste your code sample in a new file.
  2. On your keyboard type CTRL + F.
  3. Switch to the Replace tab.
  4. In the Find what:  field, type > 
  5. In the Replace with: field, type &gt; 
  6. Click Replace All in All Opened Documents.
  7. In the Find what:  field, type < 
  8. In the Replace with: field, type &lt; 
  9. Click Replace All in All Opened Documents.
  10. On the Edit menu, select Blank Operations, then click TAB to Space.
  11. Copy the code sample and paste it in your RoboHelp topic between the <pre><code> and </code></pre> tags.

The screenshot above shows what your pasted code looks like after inserting it.

But wait!

There are a few things you need to know about when working with topics.

    • Once you paste the second code block in, do not switch back to Design view for the topic before you place your code sample in. RoboHelp doesn’t like the <code> tag inside of the <pre> tag and will delete it if you do not have content inside of the tags.
    • Add pre to your .css file if you want to further style the code block by adding margins, changing fonts, etc. Watch out, though, because RoboHelp doesn’t really like this, either. Always keep a backup of your css file, as RoboHelp will delete this pre class if you edit the css file using the RoboHelp stylesheet editor.
    • Add a class to your css file, I use .long, to add a max-height or other specific styling to code blocks when the code sample is very long. I have some pages with multiple code samples that I use class=”long” on to limit the blocks to 200px in height.

      Code blocks all with max-height set to 200px and overflow set to auto.
      Multiple code blocks in one topic.
    • Always preview your topic to make sure the highlight is working. It will not display in a formatted manner inside of your RoboHelp editor, it will look like a div. If the preview doesn’t display properly, look at the path to the highlight.pack.js file in the topic heading, and check to make sure that you did your code sample prep work before pasting it in the page.

Final product

This is what your code sample will look like, or what mine does based on my selected style (blurs added to protect privacy):

The same code that is in the screenshot above, but in the published topic.
Code block in a topic

Did I miss anything? Have you been able to get a different prettyprint package to work with RoboHelp? Please let me know in the comments!

Chrome vs. RoboHelp HTML5 Responsive Output

Posted on by admin

So, just a quick post in case this happens to anyone else. Of note:

  • I am using a very customized version of the Charcoal HTML5 responsive layout.
  • I am using RoboHelp 2017.
  • I am using Chrome 63.0.3239.108, 64-bit.

So, I noticed I couldn’t search in google chrome, though it worked fine in other browsers. Nothing on the interwebs, no hints. I could type in a search term, the suggested searches would populate just fine, but hit enter and nothing.

Long story short:

  1. In Chrome, click the [more icon, three vertically stacked dots at the top right of the browser].
  2.  Click Settings.
  3. Scroll down, then click Advanced.
  4. Click Content settings.
  5. Click Cookies.
  6. Deselect Block third-party cookies.

That oughtta do it.

Disability Types

Posted on by admin

Let’s start today’s post off with an overview of the disability types we need to think about when we create accessible documentation.

There are five major disability groups that we need to consider when creating documentation:

  • Visual. Visual disabilities include blindness, low-vision, and color-blindness. As writers, our main target is readers, so it only makes sense that our most heavily hit area in our quest for Accessibility Zen will be Visual Accessibility. I have many tricks and tidbits for you, and I really can’t wait to talk to you about a new advance on the horizon from Samsung that will enable us to help our Braille readers get closer to being able to use our documentation in a meaningful, and faster, way. We’ll also discuss image accessibility, and I’ll provide examples of how to make accessibility happen in the tools that you use every day, including RoboHelp, Madcap Flare, wikis, HTML, and Word/PDF documents.
  • Auditory. This section covers those individuals with mild, moderate, severe, and profound hearing loss of varying types, including conductive, neural, high and/or low tone hearing loss. Some individuals fall under both the deaf and blind categories. From a Technical Communications point of view, we’ll talk about how to make our multi-media content accessible to deaf users.
  • Motor. Motor disabilities are any disability that affects the user’s ability to interact with your document, such as spinal cord injury, muscular disability, limb loss, or multiple sclerosis. Expect our discussion about this topic to be interesting—we’ll make a case for eschewing all of the fun little bells and whistles that technical communications tools give you, like expanding hotspots, pop-ups, and things of that nature that users with motor issues may have a more difficult time with in favor of making your documentation mouse-click-free.
  • Cognitive. Many people have some form of cognitive disability that affects their use of content, such as memory problems, problem solving and attention issues, visual or math comprehension disabilities, or reading, linguistic, and verbal comprehension problems. Don’t make the mistake of discounting this group! You likely know several people that fit in this “box,” including friends with dyslexia, ADHD, Autism Spectrum Disorder. Tehnical Communicators are compliant with this section as a rule—we write for clarity and simplicity—but there are a few quick, simple things to add to documentation that will step it up a notch.
  • Seizure. Individuals with seizure disorders have a very limited, but nonetheless important, set of accessibility features. Generally, the goal is to avoid strobing and pulsing lights, and we’ll discuss that in a little more depth when we get there.

I’m planning to keep these posts bite-sized so that you can digest the information and begin incorporating the suggestions into your own writing. So, think about how (or if) you already make information accessible in your position, and keep on following these posts. By the time I’m done, you’ll be the accessibility expert in your organization!

I’ll see you in a few days and we’ll talk about resources–where you can look to find out about current accessibility standards.

WHY ACCESSIBILITY?

Posted on by admin
A square image with four smaller squares inside, each a white image against a blue field. The images are line drawings of common symbols. Top left is the handicapped symbol, bottom left is the deaf/hard of hearing symbol, bottom right is the blind/visually impaired symbol, and top right is the mental handicapped symbol.

BACKGROUND

I’m currently working for a company that manufactures payment terminals, and, due to some interesting events in my life that coincided with this, have been thinking about how my friends and loved ones with disabilities would view my work.

Because of the manner of my work, I’m in a unique position to implement accessibility standards in this company. I’m re-working the company’s documentation delivery process, getting all of their content set up in Madcap Flare so they can use and reuse content in an effort to save time and effort in future documentation tasks. This opportunity, intersecting with my current interest in learning all about accessibility standards and ways of implementation, is allowing me to help get this company set up to succeed in the future with, full Section 508 compliance.

In parallel to this Madcap project, I’m helping to create a style guide for the company to use, and I can include 508 compliance standards in that guide as we go forward.

WHY CREATE ACCESSIBLE DOCUMENTATION?

Ask yourself why you create documentation. What are your goals? What do you want the end result to be? Generally speaking, most of us want to create documentation that is:

  • Easy to navigate
  • Easy to read
  • Provides useful information that cannot be found in the UI.
  • Allows users to interact with your documentation and provide feedback.
  • Leaves users with positive feelings about the product and the company.
  • Reduce the number of times a user needs to call in for assistance.
  • Save the company money on support calls.
  • Drive revenue for a company/product by providing valuable information for potential customers.

All of those answers, all of the major goals of TechComm, also provide the answer to the question, “Why create accessible documentation?”

  • If a blind user cannot navigate your documentation, it is not useful to him/her.
  • If a color-blind user cannot read your documentation because of your font color choices, the documentation is not only inaccessible, it’s useless.
  • If a dyslexic user is not able to easily read your documents, you aren’t accessible.
  • If a deaf customer has to call in on a TTY for support because all of your documentation is in video format, you aren’t accessible.

Essentially, if you have even one customer that cannot use your documentation in the way it is intended, your goals as a technical communicator are not being fully reached.

GOVERNMENT COMPLIANCE

If your company provides services to the United States Government, you NEED to be compliant with Section 508, it’s required. I hope the posts I write over the following weeks/months will help you to do that.

THEY DON’T TEACH THIS STUFF IN TECH WRITING SCHOOL!

Unless you specifically sought out information about accessibility when you were learning how to be a Technical Communicator, you probably had no idea that documentation accessibility was even a thing. I know I didn’t, and none of my professors even brought it up. That’s why I’m writing these articles; I know there are others out there, like myself, who want to provide accessible documentation, but don’t have a clue how to do it. If you’re one of us, subscribe to the blog via RSS, or follow me on social media to see when new blogs are posted.

WANT TO KNOW MORE?

Expect a flurry of posts from me over the following weeks about implementing Accessibility in your own documentation, and please, feel free to add anything, ask questions, and generally post whatever in the comments!

Rarities

Posted on by admin

When I separated from CWIE Holding Company, I was given permission to use anything that is externally published (KB articles, User Guides, etc..) in my portfolio, but some of the skills and document types that I’d like to showcase in my portfolio are not externally available. Because they have been my only employer for the last decade that has left some holes in my portfolio. Let’s talk about how I’m going to fix that. When reviewing my portfolio, the first, and biggest, black hole is samples of documents using Word. I consider myself to be an expert at word (and passed the certification exam in 2010… contemplating doing it again), and having a hole that large just will not do. Today I figured out a great way to fill the hole–I created a whole new set of documents using a “made-up” company.

Maybe I should define “made-up”… I used a company called Canyon Chameleons, and created a logo using a free logo generator, and went to town creating templates, a form, a guide, and an employee offer letter. I actually own the Canyon Chameleons domain, and I keep and raise chameleons and intend to breed them in the future, which is why I bought the domain. Of course, I’ve made all of these things before, many times over the last decade and longer, but without permission I cannot share them. Creating some stand-ins is the best of both worlds–I get to show you what I can do in Word, and I also get some of my future work done. 😉 Head on over to the MS Word page to take a look at what I came up with!

Using LiveCycle Designer Forms in DocuSign

Posted on by admin

When creating templates in DocuSign, PDF forms created using LiveCycle Designer do not upload, and do not give an error message. This makes things a little difficult, because LiveCycle forms are just prettier than you standard, every-day forms!

No need to fear, though, I have figured out the solution:

  • Create and save the form in LiveCycle Designer.
  • Open the form in Acrobat Pro.
  • Click File > Print, then select Adobe PDF for the printer.
  • Click Print.
  • Enter a name for the new file, then click Save.
  • Return to the DocuSign admin and upload the document into the template that you were previously creating.

I know, it really doesn’t make a lot of sense why you should need to take a document that is already a PDF and convert it to… A PDF!! It seems that the DocuSign system just doesn’t recognize the XML formatting that LiveCycle Designer uses to create beautiful forms as a valid PDF, so re-saving it as a PDF in Acrobat takes care of that for you.

It would also be prudent for me to tell you that you need to do this again any time you make changes to the document in LiveCycle Designer. Yes, every time. Sorry!