Archive for the ‘Docs’ Category

Frameworks, everywhere… and no documentation

Even as many claim that Delphi is on the wane, we see more and more open source frameworks cropping up. Large or small, they all being something to the table, and some are very powerful. All have been created in response to a perceived need, necessity being the mother of invention.

Unfortunately, one characteristic most of them share is a lack of documentation. It is all well and good to believe that you write self-documenting code, but it is best to remember that you are, after all, immersed in the work you are doing, so of course, once you are there, it seems obvious.

To many of the rest of us, it is far less obvious. Write comments, at the very least. Better yet, write actual documentation. It is becoming a lost art. And if or when you do write documentation, don’t be a syntax fanatic in your code and dismissive of syntax in your writing. They are of equal importance.

You may write a framework that none of us should be without, but if we can’t quickly get a sense of why it exits and how to use it, many of us will simply turn away, as we don’t need yet another hobby, or worse, a science project.

Categories: Docs Tags: , ,