Maybe it’s time to revisit .NET documentation

I saw an article today that raises the possibility, for me, that .NET documentation might nearly have returned to it’s state in the early days of .NET 1.  (In those days a tool called NDoc gave great code documentation in a variety of formats.)

It’s called Taming Sandcastle: A .NET Programmer’s Guide to Documenting Your Code at Redgate’s Simple Talk blog.

This entry is a note to myself to take a look at the article when I make the time.

Note on background:

In the NDoc days I used to produce the sort of documentation that I think is right. Decent text descriptions, diagrams of the application and theory… Basically my design notes in a nice CHM, which wasn’t just a machine generated file. It wasn’t hard.  And I really love that CHM format.  It has a nice precompiled index.  Astonishingly powerful.  (I wonder if internal politics sabotaged this technology which had such great potential.)

Then along came the NDoc collapse. Even though I didn’t like the license I volunteered to lend a hand. I never even got a reply. Go figure!

I have never really dabbled in Sandcastle, having seen enough comments, from programmers who seem to share my views, that indicated it had never really arrived!

This article gives me some hope that it might be usable now.


Side note:  As a side project, the article above was converted to ePub format.  (This is one of the formats for eBooks.)  This apparently took a surprising amount of effort.  I tried to test the ePub file, but failed.  It could not be read by the two ePub readers that I used (MobiPocket and ICE).  Though two other ePub’s that were tested on Mobi worked as expected.  This, and the really odd designs I encountered, confirmed that this is a dynamic and dangerous field.  It also shows that you can still find programs that seem to come from an alternate universe.  (If this field takes off there will be a need for tests tools like Litmus which checks out your email in different mail readers.)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: