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.
By Erik Dietrich
Ghost Doc Says the Damndest Things
Category: .NET Tags: C#, Comments, GhostDoc, SubMain | 5 Comments
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, which can help both with code comment maintenance and the generation of help documentation.
Some years ago, I was doing work for some client or another. Honestly, I have no recollections of specifics with the exception of a preference for exhaustive commenting. Every class, every method, every property, and every field.
Of course, I didn’t learn this at first. I didn’t even learn it in a reasonable time frame. Instead, I learned it close to handover time. And so things got a little desperate.
Enter GhostDoc, My Salvation
Now, depending on your perspective, you might scold me for not diligently commenting all along. I will offer the explanation that the code had no public component and no intended APIs or extensions. It also required no “why” types of explanations; this was simple stuff.
The client cited policy. “We comment everything, and we’re taking over this code, so we want you to do the same.” Okie dokie.
Now, I knew that in a world of code generation and T4 templates, someone must have invented a tool that would generate some sort of comments or another. At the time, a quick Google search brought me to a saving grace: the free tool GhostDoc.
While it did not allow me to carpet bomb my code with comments in a single click (and understandably so), it did allow me to do it for entire files at a time. Good enough. I paid my non-commenting penance by spending an hour or so commenting this way.
And do you know what? It generated pretty respectable comments. I recall feeling impressed because I expected empty template comments. Instead, GhostDoc figured out how to string some verbs and nouns together.