DaedTech

Stories about Software

Jul
12

By

Add Custom Content to Your Documentation

Category: Uncategorized Tags: , , , |

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.

Read More

Jul
3

By

You Can Use GhostDoc’s Document This with JavaScript

Category: .NET Tags: , , , |

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 for your code documentation and help file generation needs.

If you haven’t lived in a techie cave the last 10 years, you’ve probably noticed JavaScript’s rise to prominence.  Actually, forget prominence.  JavaScript has risen to command consideration as today’s lingua franca of modern software development.

I find it sort of surreal to contemplate that, given my own backstory.  Years (okay, almost 2 decades) ago, I cut my teeth with C and C++.  From there, I branched out to Java, C#, Visual Basic, PHP, and some others I’m probably forgetting.  Generally speaking, I came of age during the heyday of object oriented programming.

Oh, sure I had awareness of other paradigms.  In college, I had dabbled with (at the time) the esoteric concept of functional programming.  And I supplemented “real” programming work with scripts as needed to get stuff done.  But object oriented languages gave us the real engine that drove serious work.

Javascript fell into the “scripting” category for me, when I first encountered it, probably around 2001 or 2002.  It and something called VBScript competed for the crown of “how to do weird stuff in the browser, half-baked hacky languages.”  JavaScript won that battle and cemented itself in my mind as “the thing to do when you want an alert box in the browser.”

Even as it has risen to prominence and inspired a generation of developers, I suppose I’ve never really shed my original baggage with it.  While I conceptually understand its role as “assembly language of the web,” I have a hard time not seeing the language that was written in 10 days and named to deliberately confuse people.

Read More

Jun
5

By

Ghost Doc Says the Damndest Things

Category: .NET Tags: , , , | 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.

Read More

May
16

By

Customizing Generated Method Header Comments

Category: .NET Tags: , , , | 2 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, the subject of this post.

Last month, I wrote a post introducing you to T4 templates.  Near the end, I included a mention of GhostDoc’s use of T4 templates in automatically generating code comments.  Today, I’d like to expand on that.

To recap very briefly, recall that Ghost Doc allows you to generate things like method header comments.  I recommend that, in most cases, you let it do its thing.  It does a good job.  But sometimes, you might have occasion to want to tweak the result.  And you can do that by making use of T4 Templates.

Documenting Chess TDD

To demonstrate, let’s revisit my trusty toy code base, Chess TDD.  Because I put this code together for instructional purposes and not to release as a product, it has no method header comments for Intellisense’s benefit.  This makes it the perfect candidate for a demonstration.

If I had released this as a library, I’d have started the documentation with the Board class.  Most of the client interaction would happen via Board, so let’s document that.  It offers you a constructor and a bunch of semantics around placing and moving pieces.  Let’s document the conceptually simple “MovePiece” method.

Read More

May
8

By

Intro to T4 Templates: Generating Text in a Hurry

Category: .NET Tags: , , , , | 2 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, take a look at GhostDoc.  In addition to comment generation capabilities, you can also effortlessly produce help documentation.

Today, I’d like to tackle a subject that inspires ambivalence in me.  Specifically, I mean the subject of automated text generation (including a common, specific flavor: code generation).

If you haven’t encountered this before, consider a common example.  When you file->new->(console) project, Visual Studio generates a Program.cs file.  This file contains standard includes, a program class, and a public static void method called “Main.”  Conceptually, you just triggered text (and code) generation.

Many schemes exist for doing this.  Really, you just need a templating scheme and some kind of processing engine to make it happen.  Think of ASP MVC, for instance.  You write markup sprinkled with interpreted variables (i.e. Razor), and your controller object processes that and spits out pure HTML to return as the response.  PHP and other server side scripting constructs operate this way and so do code/text generators.

However, I’d like to narrow the focus to a specific case: T4 templates.  You can use this powerful construct to generate all manner of text.  But use discretion, because you can also use this powerful construct to make a huge mess.  I wrote a post about the potential perils some years back, but suffice it to say that you should take care not to automate and speed up copy and paste programming.  Make sure your case for use makes sense.

The Very Basics

With the obligatory disclaimer out of the way, let’s get down to brass tacks.  I’ll offer a lightning fast getting started primer.

Open some kind of playpen project in Visual Studio, and add a new item.  You can find the item in question under the “General” heading as “Text Template.”

newtexttemplate

Give it a name.  For instance, I called mine “sample” while writing this post.  Once you do that, you will see it show up in the root directory of your project as Sample.tt.  Here is the text that it contains.

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".txt" #>

Save this file.  When you do so, Visual Studio will prompt you with a message about potentially harming your computer, so something must be happening behind the scenes, right?  Indeed, something has happened.  You have generated the output of the T4 generation process.  And you can see it by expanding the caret next to your Sample.tt file as shown here.

samplett

If you open the Sample.txt file, however, you will find it empty.  That’s because we haven’t done anything interesting yet.  Add a new line with the text “hello world” to the bottom of the Sample.tt file and then save.  (And feel free to get rid of that message about harming your computer by opting out, if you want).  You will now see a new Sample.txt file containing the words “hello world.”

Read More

« Older Posts