Documenting Components – a mini-review

I have a love/hate relationship with documenting my code and components.  Similar to working out on a treadmill or lifting weights, I hate doing the work but I love the results.  🙂  I am of the firm opinion that documentation is what separates professional code from merely good code.  Your code can be the most well-tested and fully featured code in the world, but, unless your code is extremely small, it will always be an amateur product without documentation.  Documentation (along with demos) is required in order for your users to have even the hope of fully using the features of your classes and components.  (I must admit Embarcadero has been guilty of poor documentation; the only saving grace is that they provide the source code and Delphi was at the time so far ahead of other products.  Still, it can take years to figure out their code without documentation).  All things being relatively equal, I will always choose the package that has the better documentation (sometimes even when it is not so equal).

All that said, I have been documenting Delphi components for almost 20 years.  I do not officially release a component until its documentation is done.  Unfortunately, that is a lot of work, and I have to admit that I have failed to create (or more accurately maintain) proper documentation.  It feels like it must be an exaggeration, but documentation seems to take as much time as actually producing the code.  Anything that can make process faster, more accurate, and better is worth it.

I started out using HelpScribble, which for its time was pretty good and reasonably priced.  It would scan your code and generate a skeleton for you to fill in.  The output looked pretty good.  But maintaining your help documentation was a real problem.  Change your code and that skeleton was out of date, and there was no way to rescan the code and only have changes added.  I spent many years trying to fix or overcome HelpScribble’s issues by making a companion application, HelpScribble Apprentice.  HelpScribble had many shortcomings, and it only got worse as time went on as there were few updates.

Which brings me to Documentation Insight by DevJet Software.  Several years ago, I made the leap and switched to Documentation Insight for all new products.  I am extremely glad I did.  Documentation Insight is the best product for documenting Delphi components I have ever used.

Having the documentation embedded with the code is a game changer.  I know other languages have had this for years (see JavaDoc).  However, for Delphi, this was transformational.  Change the code, and the generated documentation will change too.  The integrated DocInsight in the IDE will show the documentation when you hover over a class property or method (when it is working 🙁 ) .  If you browse to the actual code, you can see the documentation right there.  Often, you do not need to even bring up the help file.  It just makes you a more productive programmer using code documented with Documentation Insight.

Documentation Insight handles most of the messy details for documenting code you write.  When you generate help files, it automatically creates links for class hierarchies and types.  It automatically organizes topics into properties, events, and methods.  Change the name of a method or property, the help topic updates (though not links you created to it unfortunately).  Change names of parameters in a method, it changes (though if you documented the old parameters, you need to change it manually).  Change the types of parameters, ditto.  Change the number of parameters, yup.  Maintaining help documentation for components is so much easier with Documentation Insight.  By having the documentation right there next to the code, it encourages you to change the documentation immediately rather than waiting.  I also like that you can create Help & Manual projects, web documentation, or standard .chm documentation.

That said, just like with creating documentation itself, I have a love/hate relationship with Documentation Insight.  Documentation Insight is the best product for documenting Delphi components, true, but sometimes it can be an incredibly frustrating tool for documenting code too.

For a start, it is buggy.  Thankfully not so much when you are writing your help topics (it would be disastrous if it corrupted source code), but when generating the documentation. (See here for an example.  Scroll down to Options under properties.  Note that even though this output is from Help & Manual, I have verified that this is what is given to H&M by Documentation Insight.  And if you generate directly to web help, this is also what you would get.  Disclaimer, this option was generated with v3.4.10.7, which was current as of when my subscription stopped last December.  Documentation Insight’s Changelog stops even before then so it is hard to know what they fixed).

For a tool that is all about producing documentation, its documentation is pretty poor too.  Too often, it is a matter of trying something, generating the help, and then checking if it worked.  Have an event property that is being classified under properties instead of events?  There is a one-line statement about what to do with no examples.  Scoping your links is a matter of trial and error.  In general, it is best to scope your links as little as possible, e.g.,

<see cref=”Assign”>Assign</see>

instead of

<see cref=”MyUnit|TMyClass.Assign”>Assign</see>

Doing your scoping this way makes copying a help topic to another class easier.  However, it doesn’t always work and the reasons why are not always obvious.  By default, the links that Documentation Insight creates for you are tightly scoped so you need to edit them often.

Finally, by itself, Documentation Insight is not really enough.  You need another help tool, such as Help and Manual, for the generic topics not tied to Delphi code (e.g., Introduction, gallery, etc).  For a product so tightly focused on doing one thing, it is pretty expensive (the Enterprise version which I bought is $319) and the subscription is not worth it at all as the updates don’t justify the price.  Since the v3 release in 2013, there have only been bug fixes, updates to work in the latest versions of Delphi, and very minor improvements.  At almost half the cost of the original product per year, you are paying a high price for what are maintenance releases in other products.

In conclusion, Documentation Insight is the best product for documenting your code in Delphi and you really need to buy it if you are documenting Delphi code.  Sadly, it has some severe flaws and the subscription is overpriced, but ultimately, I think it is worth buying.  It provides the best output and maintenance for Delphi code that I have seen.  Thumbs up!  🙂

Leave a Reply

Your email address will not be published. Required fields are marked *