Writing Help files, producing documentation and manuals is hard work for even the smallest application or component set. No one likes to do it. It’s usually put off as much as possible and ends up being the last thing done. Shoot, we developers don’t even like to comment our code, much less write a help file or (horrors!) a whole book about our application!
I can’t even imagine what it is like trying to manage it for a project as complex as Delphi. There’s really three large tasks: documenting the product itself, the language, and the framework. Then, of course, there is the task of tying it all together into a single entity, making the help extensible, and integrating it into the IDE. The entire process represents a formidable task no matter how you look at it. The Delphi Help team is small, and I’m sure they’d all love to have about seventeen more members. And Lord knows they’ve taken a lot of heat publicly over the years. It seems no one is every satisfied with Delphi’s documentation.
Recently, however, the team has made a bold move. They’ve undertaken the interesting task of re-architecting the whole she-bang. They’ve begun to abstract out the content into XML files so that the content of the help is separate from the presentation. That way, content can be managed separately from the presentation as a book, website, help file, or whatever. The people writing the help can now concentrate on writing good help, and stop worrying about the presentation layer. This is a really smart move. But the team is still small.
Interestingly, there is a large group that is very interested in high quality documentation for Delphi and who have, in the past, displayed a willingness to help out in such areas. And that group is us. We can help make the Delphi documentation better.
And that is why I think that the Delphi help should be published as a Wiki. If you don’t know what a Wiki is you can follow the link and poke around, or you can read the next sentence. A wiki is basically a user-updateable and user-manageable website. Anyone can come and edit the content of a Wiki site. The most famous Wiki is the Wikipedia, a huge encyclopedia with thousands and thousands of contributors. Experts and non-experts alike can make entries, update entries, correct mistakes, add new and interesting information, and keep the whole thing updated and accurate. As far as I can tell, 100% of the Wikipedia has been written by volunteers. Articles are automatically linked to other articles. It’s a beautiful thing all around.
Now, imagine the entire Delphi help system published as a Wiki. All the current information could be published unchanged. We all could edit it, refine it, add to it, and improve it. We could add tons of illustrating code snippets. We could create link pages, and tons and tons of valuable cross references. Anyone in the world could do so at all hours of the day and night.
And I’d like it if, when I hit F1 in my IDE, I was sent to the Wiki instead of the help file if my computer is on the Internet. That way, I’d be sure to be seeing the most up to the minute information. I could also use that opportunity to make my own additions. If Borland could come up with some way of integrating the task of updating right into the IDE, then that would be even better. Making it easier to update the Wiki means that the Wiki gets updated more often.
Borland could set the Wiki up so that it automatically updated their current database of content, and then they could periodically take snapshots of the database and use that to publish their local help files and manuals. Even those could be made available for download for users during off-line periods.
Another Win/Win: Borland gets the help they need to make Delphi’s documentation top of the line, and the customer gets the help of the entire Delphi community.