Stories about Software


.NET Code Documentation So Easy It’s an Afterthought

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 if you want automated documentation for your API.

Though I’ll talk today about .NET code documentation, I want to start further back than that. And by “that,” I mean further back than .NET. I realize that may date me somewhat, but please bear with me.

Most things in the programming world date back further than you’d think. For a dramatic example of this, consider functional programming. All the rage today, it actually dates back to the 60s in practice and 30s in theory. Speculating about the reason for temporal myopia would go beyond the scope of this post, but understand that this tendency toward myopia does exist.

With that in mind, let’s talk about some GUI builders.

A Tale of Two GUI Builders

Now we get to the part that predates .NET. I’m going to reach back into my early career and compare my relatively simultaneous experience with two GUI building technologies.

First, I encountered Swing, a Java GUI toolkit. While Swing did not include a GUI builder at the time, my project packaged it with one. I cannot remember its name for the life of me, but this thing was a train wreck. Moving controls around on a form caused the spewing of improbable amounts of code into my Java classes. Attaching handlers to GUI events only half worked, requiring wire up by hand. I had such struggles with it that I gave up and just hand-coded everything in Java.

Shortly after working on that project, I found myself saddled with a VB6 application. At the time, .NET actually existed, but nobody had ported this thing to it. So I used VB6. And I loved it.

That probably sounds as weird to hear as it feels to type, but there it is. Compared to my experience with Swing and its nightmarish GUI builder, this was a refreshing summer breeze. I could move controls around to my heart’s content, wire up events easily, and get stuff done.

The Abstraction Tradeoff

With this comparison, I had my first taste of something I’ll call the abstraction tradeoff. When you create an abstraction, such as the Swing GUI builder or the drag and drop VB6 form builder, you make a tradeoff. You hide complexity from consumers, but you take away flexibility and power.

When you create good abstractions, you hide stuff your consumers don’t care about, making them happy. When you create poor or mismatched abstractions, you can fail to hide the complexity from them and you can also take away vital capabilities.  Making a good conceptual abstraction thus becomes something of a gauntlet. With me as an audience, VB6 walked it well while Swing and its GUI builder did not.

To think of it another way, abstractions create tradeoffs. But when you create ones well-suited for your audience, you create a situation where neither side of the tradeoff represents a downside. You can have users grateful for hidden complexity while missing none of the flexibility. But you can also get both of these things wrong, failing to hide complexity while handcuffing your users. Frameworks that get both wrong line the dustbin of history.

Documentation, Historically

Let’s put aside, for the moment, abstractions and GUI builders. We’ll return, I promise. But before you can place an abstraction over something, you need to understand how it works. So let’s talk about the historical generation of documentation for software.

For much of the history of software, developers would develop and writers would write. In other words, you would spend your time writing code, and your organization would hire technical writers later to document the resultant software.  Generally, in large waterfall shops, this would happen during the QA phase, after development had mostly solidified. Before the release (ideally), the tech writers would use release notes and project managers to put together a user manual.

Of course, this assumed your software had non-technical end users. If you targeted developers, then the developers would generate documentation like this, from the Linux man pages.

But over the last decade, perhaps spurred by the usability of the original iPhone, we’ve moved toward a world that makes user experience easier. We’ve also moved toward more cross-functional approaches, gone agile, and entered a world where many more organizations create tools and APIs that target software developers.

The result? Development shops have started to create their own documentation more and more frequently.

The Windows CHM File

In the Windows world, you’ve probably seen the CHM file. For a long time now, people have distributed this with software as a digital instruction manual. I can still remember when these shipped with DVDs and CDs. But with the aforementioned push toward the new way of doing things, you’ll see dev groups themselves responsible for creating them. And you’ll also see them targeting developers more and more. If you do .NET code documentation, particularly for any sort of desktop app, you may have a hand in creating these.

You can use a Windows tool called HTML Help Workshop to create this kind of documentation. Battleship grey and reminiscent of 90s forms applications, you can see it here, in all of its glory, in 2017.

 I say this not to disparage the tool in anyway — it serves its purpose. But it doesn’t exactly exist at the cutting edge of ease of use. Recall that I talked about walking the line of abstraction? This tool allows you to create help documentation via “compiling” and linking files and the like. We’ve gotten better over the years at building GUI abstractions that work well, but this hasn’t really caught up.

So developers tasked with building help files would have to learn this tool and undertake the laborious process of transcribing functionality into HTML Help Workshop, tweaking it, and then compiling it to see the result. Is it any wonder they’ve tried to avoid that, asking questions like this one on Stack Overflow?

Generate Help from Visual Studio

If you look through the answers on Stack Overflow, you’ll see technologies like GhostDoc. These technologies seek to cut out the intermediary transcribing step. They do this with the value proposition of, “we’ll take your actual source code and use comments to generate documentation for you.”

This creates a powerful reduction in barriers to self-help. As a developer, I no longer have to do onerous work, and I don’t have to deal with something other than the comfortable Visual Studio. Now I’m much more likely to generate help documentation in a tight timeline. It no longer seems laborious or as though it will substantially slow me down.

From the perspective of abstractions, this becomes a much better one. I don’t want to understand details of how help files are organized and linked together. I don’t want to “compile” them. I just want one made for me based on my code; I’ll tweak as needed. And tools like GhostDoc get you there.

.NET Code Documentation in the Future

But today, one annoyance still remains. I don’t have a tight feedback loop, and I don’t have a killer abstraction. Not worrying about the layout of the CHM file is great, and not thinking about “compiling” it makes me happy. But I still have to go into my Visual Studio solution, generate it, look at the results in a new window, and then tweak by doing that all again. I’d appreciate a more seamless abstraction. I’d appreciate a WYSIWYG.

And that WYSIWYG will come in the newest version of GhostDoc. As always, you’ll have the ability to generate a help file directly from your code. But now, you’ll have the ability to edit the help file in-situ, with changes being saved back to the file contents and to your code comments as needed.

This makes the generation of help files so easy that barriers to entry simply melt away. .NET code documentation becomes an afterthought in terms of help files. Generate it whenever you want, tweak it effortlessly, and have it persist. As we see by my fond memories of the VB6 form editor, good abstractions stay with you and stand the test of time. When it comes to your help documentation, you’re going to like this abstraction.