Help on Help
The MS Help2 viewer is packed with features that are not always obvious. Kris Houser has posted an article about how to best use the RAD Studio Help. My favorite tip is how to use the Tools/Options/Help/Online dialog box to specify whether Search will include external sources or only RAD Studio help. By default the search traverses a variety of sources that are not of interest to me, so I restrict my searches to the "Local Help" that CodeGear provides. Thanks Kris!
Share This | Email this page to a friend
Posted by Dee Elling on February 7th, 2008 under Uncategorized | 23 Comments »Docs on the Web
I’m a big believer in putting technical docs "live" on the web, especially for products that are web-oriented and/or whose customers are intense internet users. The tech docs at my alma mater WebLogic were a strategic advantage in the Java community; developers went to that website for the best J2EE docs no matter what software they owned. If you googled a J2EE term it was usually WebLogic doc at the top of the results. Great for company "mindshare" and great for customers too!
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
Posted by Dee Elling on January 11th, 2008 under Uncategorized | 26 Comments »RAD Studio Help Update and CHMs
It’s January and time to catch up on the latest activities of the RAD Studio docs team. Last November we released the first ever Help Update and that went very well. Special thanks to our Field Testers! For those who prefer the HTML Help format, we released CHM versions on CodeCentral. In between the holidays we continued improving the help and plan to release another Update soon. We’re also ramping up on the next big release of RAD Studio, so there are interesting things to learn, plan, and write about Unicode and other features.
Share This | Email this page to a friend
Posted by Dee Elling on January 11th, 2008 under Uncategorized | 8 Comments »Examples on CodeCentral
Our Delphi examples writer Rick Dickason has started posting the packages for the examples that are in the RAD Studio Help. Actually, with the first two he is a bit ahead of the Help… they will be included in Help Update 1, soon!
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
Posted by Dee Elling on September 28th, 2007 under Uncategorized | 2 Comments »Releases Galore and Delphi Examples
We’ve had a flurry of releases the last few weeks! JGears, RAD Studio 2007 with Blackfish SQL, and the new kid on the block 3rdRail with veteran InterBase. Coming up for air, I’m starting to take in the feedback and work on the upcoming round of updates.
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
Posted by Dee Elling on September 18th, 2007 under Uncategorized | 5 Comments »Old Help and New
I get lots of questions about why the newer RAD Studio help systems have so much less information than the older versions. Many customers keep the old help around because the new help is still not on par! This of course was a big shock to me; I’ll share a bit of what I know about the situation and what we are doing about it.
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:
- 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!
- 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.
- 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!
- The content was never written. The team is enlisting the help of our engineers to cover these outages.
- 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
Posted by Dee Elling on August 21st, 2007 under Uncategorized | 33 Comments »English CHMs (HTMLHelp) for RAD Studio 2007 posted
See RAD Studio Delphi 2007 Help CHM Files or RAD Studio C++Builder 2007 Help CHM Files for HTMLHelp versions of the current English Help. These contain some bugfixes from June 1 to Aug 3, including "restoration" of many files for namespaces such as Classes.
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
Posted by Dee Elling on August 7th, 2007 under Uncategorized | 13 Comments »More RAD Studio 2007 PDFs posted
Check out C++Builder Documentation Submissions for English, Japanese, French, and German editions of the C++ Reference.
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
Posted by Dee Elling on August 1st, 2007 under Uncategorized | 3 Comments »Goals of the CodeGear docs team
I’ve recently been rolling out my plans to the CodeGear Engineering team and want to start sharing them with you. The docs team now has a few high-priority tactical goals and some strategic ones. Here’s our list:
Tactical
- RAD Studio content: restore and fill in missing content
- RAD Studio content: provide information to help new users get going
- Update mechanisms: use patch update, auto update, and Eclipse update
- Accessibility: put content on the web, using CDN article-style technology and PDFs for download
- InterBase content: fix doc bugs and provide notes for the service pack
- Agile doc development: sprinting along with the Ruby/Rails team
- Modularize content: flexibility for JBuilder releases
Strategic
- Managed collaborative documentation: wiki inside and out
- Team: add more technical skills to the team mix
- Productivity: automate, automate, automate
I’ll talk more about each one in future blogs. It sounds a bit dry right now but each of these projects will be very interesting!
Share This | Email this page to a friend
Posted by Dee Elling on July 16th, 2007 under Uncategorized | 14 Comments »Recent activities on the doc front
Thanks for all of your comments and suggestions! I’ll point out a few activities of the recent weeks that relate to some of your suggestions. I just participated in my first full product cycle, C++Builder 2007, and it taught me a lot about the work ahead and helped focus my goals for CodeGear product technical information. Later I’ll write more about those plans.
For the C++Builder 2007 release, Chris Benson and Chris White made important fixes to the Help infrastructure, such as the F1 and the filters. On the content side, the writers started going through our doc bug backlog and made a tiny dent; the important thing is that doc bugs are now part of our daily conversations and activities. Also on the content side, we started some of the "archeology" needed to restore content from previous releases. We are far from where we need to be with the RAD Studio content, but we have begun the journey.
Another recent activity was posting doc files to CDN/Code Central. We are using the file upload technology available in the "Examples" section to post ZIPs of either HTML or PDF or both. (I know Examples is not an intuitive place to find docs, but it was the fasted way to get the files out there! We are planning website changes in the future that will make it easier to find our technical information.) I started by posting some of the older doc sets from the Borland site. Yesterday I posted various configurations of the RAD Studio Help system. I hope you find them useful, if not perfect yet!
Some of you may be wondering if anyone is reading the "Documentation Feedback" emails. Well that would be me; I am going through a large backlog of emails. If I know that we already addressed the problem, I will respond. If not, I will hold onto it until we do. Unfortunately I cannot respond to each and every email to thank you for your feedback right away, so I’m saying it here: Thanks and keep it coming!
Share This | Email this page to a friend
Posted by Dee Elling on June 27th, 2007 under Uncategorized | 16 Comments »Server Response from: dnrh1.codegear.com
