DaedTech

Stories about Software

By

Add Custom Content to Your Documentation

Editorial note: I originally wrote this post for the SubMain blog.  You can check out the original here, at their site.  While you’re there, have a look at GhostDoc not only to help you with comment management and generation, but also to help you construct automated help documentation.

For the last several years, I’ve made more and more of my living via entrepreneurial pursuits.  I started my career as a software developer and then worked my way along that career path before leaving fulltime employment to do my own thing.  These days, I consult, but I also make training content, write books, and offer productized services.

When you start to sell things yourself, you come to appreciate the value of marketing.  As a techie, this feels a little weird to say, but here we are.  When you have something of value to offer, marketing helps you make interested parties aware of your offer.  I think you’d like this and find it worth your money, if you gave it a shot.

In pursuit of marketing, you can use all manner of techniques.  But today, I’ll focus on a subtle one that involves generating a good reputation with those who do buy your products.  I want to talk about making good documentation.

The Marketing Importance of Documentation

This probably seems an odd choice for a marketing discussion.  After all, most of us think of marketing as what we do before a purchase to convince customers to make that purchase.  But repeat business from customer loyalty counts for a lot.  Your loyal customers provide recurring revenue and, if they love their experience, they may evangelize for your brand.

Providing really great documentation makes an incredible difference for your product.  I say this because it can mean the difference between frustration and quick, easy wins for your user base.  And, from a marketing perspective, which do you think makes them more likely to evangelize?  Put yourself in their shoes.  Would you recommend something hard to figure out?

For a product with software developers as an end user, software documentation can really go a long way.  And with something like GhostDoc’s “build help documentation” feature, you can notch this victory quite easily.  But the fact that you can generate that documentation isn’t what I want to talk about today, specifically.

Instead, I want to talk about going the extra mile by customizing it.

Introducing “Conceptual Content”

You can easily generate documentation for your API with the click of a button.  But you can also do a lot more.

GhostDoc feature something called “Conceptual Content.”  Basically, it allows you to customize and add on to what the engine generates using your code and XML doc comments.  This comes in handy in ways limited only by your imagination, but here are some ideas.

  • A welcome page.
  • A support page.
  • A “what’s new” page.
  • Including a EULA/license.
  • Custom branding.

You probably get the idea.  If you already look to provide documentation for your users, you no doubt have some good additional thoughts for what they might value.  Today, I’m going to show you the simplest way to get going with conceptual content so that you can execute on these ideas of yours.

How It Works at a High Level

For GhostDoc to work its documentation-generating magic, it creates a file in your solution directory named after your solution.  For instance, with my ChessTDD solution, it generates a file called “ChessTDD.sln.GhostDoc.xml.”  If you crack open this file, you will see settings mirroring the ones you select in Visual Studio when using GhostDoc’s “Build Help Documentation.”

To get this going, we face the task of basically telling this file about custom content that we will create.  First, close out of Visual Studio, and let’s get to work hacking at this thing a bit.  We’re going to add a simple, text-based welcome page to the standard help documentation.  To do this, we need the following things.

  • Modifications to the Ghost Doc XML file.
  • The addition of a “content” file describing our custom content,
  • Addition of a “content” folder containing the AML files that make up the actual, custom pages.

Let’s get started.

The Nuts and Bolts

First, open up the main GhostDoc XML file and look for the “ConceptualContent” section.  It looks like this.

    <ConceptualContent>
      <ContentLayout />
      <MediaContent />
    </ConceptualContent>

In essence, this says, “no conceptual content here.”  We need to change that.  So, replace the empty ContentLayout entry with this (substituting the name of your solution for “ChessTDD” if you want to follow along with your own instead of my ChessTDD code.)

<ContentLayout file="ChessTDD.content" folder="Content\" />

Next up, you need to create the file you just told it about, ChessTDD.content.  This file goes in the same directory as your solution and looks like this.

<?xml version="1.0" encoding="utf-8"?>
<Topics>
  <Topic id="4684cc2f-3179-4871-b7a4-ad69f0f260a3" visible="True" isDefault="true" title="Welcome">
    <HelpKeywords>
      <HelpKeyword index="K" term="Welcome" />
    </HelpKeywords>
  </Topic>
</Topics>

For the ID, I simply generated a GUI using this site.  This ID simply needs to be unique, and to match the next file that we’ll create.  Next up, create the folder you told ContentLayout about called, “Content.”  Then add the file Welcome.aml to that folder, with the following text.

<?xml version="1.0" encoding="utf-8"?>
<topic id="4684cc2f-3179-4871-b7a4-ad69f0f260a3" revisionNumber="1">
  <developerConceptualDocument
    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink">
    
    <introduction>
      <para>Welcome to our help section!</para>
    </introduction>

  </developerConceptualDocument>
</topic>

Notice that we use the same GUID here as in the content file.  We do this in order to link the two.

Let’s Give it a Whirl

With your marked up Ghost Doc XML file, the new content file, and the new Content folder and welcome AML file, you can now re-launch Visual Studio.  Open the solution and navigate through GhostDoc to generate the help documentation CHM file.

There you have it.  Now you can quickly add a page to the automatically generated help documentation.

Keep in mind that I did the absolute, dead simplest possible thing I could do for demonstration purposes.  You can do much more.  For example:

  • Adding images/media to the pages.
  • Have cross-links in there for reference.
  • Add snippets and examples.
  • Build lists and tables.

As I said earlier, you’ll no doubt think of all manner of things to please your user base with this documentation.  I suggest getting in there, making it your own, and leaving a nice, personal touch on things for them.  When it comes to providing a good user experience, a little can go a long way.