Documentation Archives - Software Quality Blog

Can We Retire the Design Document, Already?

February 13, 2018Erik DietrichNo Comments

In the interest of running a social experiment to amuse myself, I won’t do a Google search for the term design document. I could easily do this, but I won’t. Instead, I’m going to hazard a guess as to what the search would yield: a Wikipedia article and a bunch of really old web pages that use the passive voice a lot. I say this because design documents, like the singleton design pattern and systems such as Hungarian notation, were legitimately good-seeming ideas that just landed on the wrong side of history. (And like those two things, I’m sure someone will…

GhostDoc v2018 Beta 3 is available

January 30, 2018Serge BaranovskyNo Comments

(Mar 9, 2018) Update: new build v2018.0.18070 has been posted to address the VS2017 v15.6 compatibility issue. Changes in the Beta 3, build v2018.0.18030 – New feature – Document Project – now can generate XML Comment templates for a whole project Added support for the <inheritdoc> tag – for type members only in the XML Comments as well as the generated help documentation. This allows using the tag instead of copying the documentation from base members and synchronizing the changes. Visual Editor improvements New commands – Add Table, Remove Table New commands – Add Note, Remove Note Now the tags not recognized…

Different tool vendors can help you automate API documentation.

How Do You Handle API Documentation?

October 17, 2017Erik Dietrich1

The subject of API documentation reveals a fascinating property of the software development industry that makes it truly unique. When you think of a product, you think of something polished and ready to ship. That’s true of software and also of the broader world in general. But only in software can you crack the product open to reveal its internals and then ship that as well, with a different purpose. When you expose an API, this is exactly what you do. Take an offering like, say, the iconic Trello. On the surface, you have a lightweight kanban utility with a…

Code documentation and code comments are different, like red and green apples.

Code Documentation and Code Comments Aren’t the Same Thing

September 26, 2017Erik Dietrich1

Often, you hear “code comments” and “code documentation” used at least somewhat interchangeably. Perhaps the idea of code documentation has a little more formalism to it, in passing. And code comments may cover a bit less ground. But still, I hear the terms serve as synonyms for one another. And I hear this in particular when it comes to the actual construct of code comments — meaning, literally, the feature of compilers and interpreters that allows you to say, “Disregard everything after these two slashes. I’m editorializing for the benefit of other humans.” “Comment your code” and “document your code”…

GhostDoc v2018 Beta 2 is available

August 21, 2017Serge BaranovskyNo Comments

In the Beta 2, build v2018.0.230, we are continuing to build out the Visual Editor features as well as improvements and fixes New menu – Open Comment Editor – (Ctrl-Shift-E) to open Visual Editing for XML Comments Visual Editor improvements New – Insert Image New – Add/Remove Hyperlink Added Visual Editing for source code samples in XML Comment New menu and VS command – Document File Header – allows to generate/update the file header without having to re-document the file Improved performance of the Document File/Type batch actions Other improvements and bug fixes For the complete list of changes, see…

When looking for the concept of Microsoft HTML Help, it can be hard to even know what to Google.

Upgrading from Microsoft HTML Help

August 1, 2017Erik DietrichNo Comments

Before I get into talking about Microsoft HTML Help or any alternatives, let me ask you something. Have you ever had the singularly frustrating experience of staring blankly at the Google homepage? You’re staring blankly because it occurs to you that you don’t even know what words to type. Maybe this happens because you’re searching for a name that muddies the waters. Someone creates a new JavaScript framework named Taylor Swift. Or perhaps it happens because you know only vaguely how to describe the concept. Try buying a replacement cotter pin if you don’t actually know the name of the thing….

.NET Code Documentation So Easy It’s an Afterthought

July 20, 2017Erik Dietrich5

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…

Documentation Tools for Programmers

July 19, 2017Erik Dietrich1

More than a decade ago, I worked somewhere that would ship CDs containing commercial software. Along with others, I’d program applications that ran commercial mail sorting machines and provided a user interface for the operators. To update or patch the software, we’d cut official CDs and send them out in the mail. These CDs would, obviously, contain the software. But they’d also contain a rather elaborate PDF of the user’s manual. In some cases, we might mail them a physical user’s manual. And that manual was a formidable, polished document. You’re probably expecting me to complain about writing that document….

How C# Spell Check Helps Your Team and Your Code

June 27, 2017Erik Dietrich1

If you didn’t know that C# spell check was a thing, it is. For one thing, you can run a normal spelling analysis on any comments in your code. That shouldn’t surprise. But you can also check the code itself for spelling errors. That may seem like a strange thing at first. Wouldn’t a C# spell check get pretty weird on anything but single word tokens? I mean, if you look up ToString in the dictionary, you come up empty. Well, it turns out that you can solve the problem more easily than you might think. The same conventions that…

GhostDoc Pro Beta brings true Visual Editing to XML Comments

June 15, 2017Serge Baranovsky3

The latest beta of GhostDoc introduces a new feature that makes XML documentation authoring a breeze: visual editing for XML comments. The number one challenge authoring XML comments, according to our users, has been keeping the valid XML that includes encoding HTML formatting tags, code samples, etc. Many of these don’t even show up until the help docs are generated. And now we offer a solution to this. Visual editing makes it painless to insert tables, lists, pictures, links, source code samples, and other formatting directly in your XML doc comments. (Most of these are included with the beta, while…