Share This | Email this page to a friend

We’ve had the privilege of working with Delphi luminary Neil Moffatt, of Delphi Basics fame. Neil tackled many of our VCL outages during a break from his dream job as a photographer. We thank him very much and wish him all the best with weddings galore this summer! Call on Neil if you need some great photos of your events! And of course please continue to support his website as we all know how valuable it is for RAD Studio users.

Share This | Email this page to a friend

Share This | Email this page to a friend

I’m making a big push to put CodeGear’s docs live on the internet this year. We’re doing a formal requirements doc and informal requirements gathering.

So… informally… what features would you like? Here are a few on my list so far:

* viewable, browsable, searchable HTML and PDF

* user comments

* integration with the IDE Help systems

* user contributed content

What tech doc sites do you like, and why?

Share This | Email this page to a friend

Share This | Email this page to a friend

The way it works was originally envisioned by Chris Benson and Chris White did the tooling. Here’s what happens:

Rick develops packages that exercise particular classes and methods.  He puts metadata in the comments to indicate what is used. Chris’ "examples injector" runs over the packages, interprets the metadata, and inserts the examples into the correct XML source for the API reference.

The beauty of this is that the code has a higher level of quality, since it must compile. Plus, it is dynamic and automated. Also, the packages can be supplied on CodeCentral. Yet another benefit is that we can create automated tests that run the packages against future versions of RAD Studio, to validate both the example and the product.

Let us know what you think… Rick has a lot more on the way!

Share This | Email this page to a friend

I’m hearing good things about the code examples returning to the Delphi help and am happy to thank Chris Benson, Chris White, Rick Dickason, Chris Pattinson, and Spencer Kimball for making it happen. Benson has blogged about the examples project and the first round of results are in the release. Stay tuned for more Delphi and new C++ examples, and Rick is gearing up to post the existing projects to CodeCentral.

With the Eclipse Update framework and equally with the new RAD Studio Help Installer/Updater, the team will be able to release versions of Help independent of releases. Soon… after the team has a little breather!

And I haven’t forgotten about the CHM files, which were so helpful to so many customers. Soon…

Share This | Email this page to a friend

There were "a series of unfortunate events" and I am neither going to blame nor excuse what was done or not done. The underlying basic change was to convert the doc set to XML and a sophisticated and entirely scripted publishing system. The home-grown system was then replaced by the commercial system DocOMatic, which provides more robust capabilities and will better leverage the XML content in the future.

So, where did the content go? There are five aspects to the problem:

1. During the conversion to XML, the code examples were left out. Right now I have a new writer/programmer recovering those files and organizing them into a maintainable, scaleable, and testable examples system. More about that later; it’s very cool!
2. After the conversion to DocOMatic, an XML filename case sensitivity issue was discovered. The team has made numerous fixes recently, though we are not done yet.
3. Some content was misplaced during the conversion to XML. The new writing staff is busy tracking down misplaced old content at the same time that they write up the new features for Highlander!
4. The content was never written. The team is enlisting the help of our engineers to cover these outages.
5. The usability and navigation has changed and is not as polished as it needs to be. We will iterate through these issues.

By analyzing the code, DocOMatic has made visible Help outages that were previously invisible. Before, there was no way to automatically check the completeness of the reference and now there is, and everyone can see it. The boilerplate text you see, "this is foo of bar", is the signal that the content was not found. DocOMatic also has a dashboard that shows matches/mismatches and we are using that to help track our progress.

The situation has been tough, but I believe that having our content in XML format and using DocOMatic puts us in a great position to address future needs, such as a wiki interface.

I hope this answers questions about the mystery of the missing content; in a later post I’ll go into the CHM vs. MSHelp2 "massive help viewer" question. I am definitely struggling with that one!

-Dee

Share This | Email this page to a friend

I’m curious to know if the CHM versions are helpful. In my experience they are easier to use and faster than the PDF versions, which makes sense because the Help isn’t really designed to be a "book".

The drawback of the CHM version versus the MSHelp2 version is that it doesn’t automatically include the Microsoft information. However for some customers that is a plus!

Enjoy, -Dee

Share This | Email this page to a friend

Also Delphi Documentation Submissions for additional postings of RAD Studio 2007 PDF files in English, Japanese, French, and German. These apply to both C++Builder and Delphi 2007.

We are aware of some issues with the PDFs; they are not perfect. Better to get them out there to you than to delay! Also these are purely from the Help, they do not include anything that is not already in the Help. Personally I’d like to see more diagrams and images used in the PDF "book" format, since that is the best format for static visual content.

I’m very curious to see what PDF "books" are most useful. We are learning that DocOMatic can create different configurations of PDF files, based on our extensive XML repository. If you have an idea for the "perfect PDF", I’d love to hear it. Also, are raw HTML versions useful? What about standalone CHM versions?

Enjoy! -Dee

Share This | Email this page to a friend