With so much new functionality centered on the .NET Framework in D8, plus with the implementation of an entirely new Help browser (H20), we needed to take a fresh approach to the D8 documentation. Our goal was to build an entirely new foundation that we and our customers could use for years to come. This article discusses the structure of the new D8 Help system, the new XML production system, and some D8 Help tips.
The Structure of Delphi 8 Content
As part of our move to a new production system, we decided it was time to restructure our documentation. Previous to Delphi 8, Help topics could contain conceptual, procedural, and reference information all in the same topic anywhere in the Help system. Sometimes, critical procedures or configuration information would be contained (some say buried) deep within API topics. It was difficult for many customers to find the missing key that would unlock common processes, requiring a needle-in-the-haystack approach to problem solving.
In our new system, we wanted the different information categories to be unique and easy to locate. In Delphi 8, we separated topics into three distinct, logical categories with very little (if any) overlap: 1) conceptual, 2) procedural, and 3) reference. Each document type is located in a particular area of the Table of Contents (TOC), making topics easy to find using a top-down approach.
While fewer in number, concepts tend to contain the most paragraph content. Greater in number, procedures contain precise, step-oriented information with a tight focus on results. Most numerous of all, reference topics are short and to-the-point.
Concepts
Concepts are organized top-down, from the broadest to the more detailed topics. Concepts tend to be about architectures, functional areas, and feature sets, with tie-ins to related areas. In the TOC, we consider concepts so fundamental to understanding the product that we dedicate most of the preliminary top-level nodes to conceptual areas. Each conceptual node represents a broad, functional area of the product, such as ECO, ASP.NET, ADO.NET, etc. Each Help node contains a descriptive page covering the major topics, including a link to what we consider the core process of that functional area, a special kind of procedure that represents the functional area as a whole.
Procedures
If concepts are about architectures, functional areas, and feature sets, procedures are all about actions and results. Procedures are designed to be almost (but not quite) self-contained, so you can jump right into them with little, if any preparation. If you need greater contextual understanding, you can always jump back up to the relevant concepts, which are readily linked within the procedures themselves.
As mentioned in the conceptual description, most conceptual areas identify a special kind of procedure we call a core process. A core process is usually a detailed procedure that will cover all the necessities of getting a functional area up and running. Core processes can be quite extensive and even include cheats or references to sample information to try a process out to get it working. When getting started in a new area, its a good idea to generate a prototype using the sample information first.
Core processes are similar to tutorials, but they avoid the lengthy conceptual discussions that tutorials typically contain. Theyre designed to be precise and to the point, quickly identifying required settings and configurations. If you are new to a technology or simply want to understand how the product works with this technology, the core process is a good place to start.
In addition to the core process for a functional area, numerous smaller procedures identify the most common actions for that technology. Procedures often include useful configuration notes and code samples when required. If youre looking for specific coverage of the Delphi language in .NET, the Borland procedures are your best bet.
Procedures can span two or more functional areas, so they are cross-referenced in the TOC when applicable. Cross-referencing provides greater flexibility, both for users and for the writers who create the procedures. Processes often involve more than one functional area, coordinating any number of features to produce a given result. So procedure documentation can span numerous feature sets to produce the required result. Thats why we keep procedures in a separate area, loosely coupled to any number of relevant concepts.
We envision that the procedural area will grow dramatically based on user feedback. If we find that numerous users want to solve a specific kind of problem, we can design a procedure to address that specific problem. It doesnt matter how many functional areas are involved in producing a result. A procedure can address your needs.
Reference
Reference information is the lowest, most detailed level in our documentation hierarchy. We include dialogs, error messages, and of course API documentation within the reference category. We also include the Delphi Language Guide as a special kind of reference topic with extended information. While most reference topics are small, the amount of reference information is the most plentiful of the three documentation types.
As mentioned in the procedural description, we no longer put critical configuration information in the API topics, but cover typical usage scenarios in the procedures. Another key difference from past Delphi releases, we no longer produce the syntax lines or the Property, Method, and Event (PME) lists in our reference documentation by hand. Our revised production system using compiler output now handles that for us automatically.
The Documentation Production System
Its worthwhile to mention a few changes on the production end of things so that customers know how were dealing with current and future Help systems. Component writers creating their own Help and Borland partners would find this information particularly interesting.
In previous Delphi releases, we used a number of different authoring tools and many different documentation formats geared entirely toward specific Help engines. If the Help engine changed, we needed to redesign our source to conform to it or convert one arbitrary format to another. For our Delphi writers, the days of RTF, HTML, and Framemaker are now long gone.
After Delhi 7, we re-architected our production system from the ground up. We now use just one tagging format: XML, validated with W3C schemas. As a result, we use just one XML editor. We dont mark up files for appearance in a particular Help engine any more, but focus entirely on content and semantics. A Help build engineer uses XSLT downstream to add the formatting required for different Help engines. When Microsoft creates a new Help engine requiring different formatting, we adjust the XSLT script, not the XML source content.
There is a profound difference between format and semantics in documentation. In the past, a writer might add italics to a property reference within text so that it looks distinct. Now, we tag a property with a dedicated property element in XML, coding the namespace along the way. The property text now has a specific meaning. Once, marked up with semantics, we can do all sorts of things with the property text we couldnt do when merely indicating italics. (Anything, and literally anything, can be marked with italics.)
With semantics applied to the property text, we can automate link construction. We can apply whatever formatting we wantor change our minds later without impacting authors. We can even apply different formatting rules in different document types to avoid clutter. In the past, if we wanted API references to appear as bold instead of italics, wed have to manually identify PME references and change the formatting by hand, a time consuming process. Now, we change an XSLT mapping. In the near future, we envision running automatic reports to find references to API elements that have changed or no longer exist, comparing results against dynamic compiler (or assembly) output.
For API documentation, we no longer produce syntax lines and PME lists by hand. With tens of thousands of PMEs, this approach is manually intensive and error-prone. (Authors would rather write content any way.) We now pull XML directly from the compiler, automatically construct our PME lists, merge the lists with our content downstream, apply formatting with XSLT scripts, and then produce final output for the required Help engine. It sounds simple enough, but there is a lot of logic that goes into interpreting compiler (or assembly) output for each language that we currently support (Delphi for .NET, Delphi for Win32, and C#). Each language has its own set of rules to interpret.
Whats in the future? With our new documentation system based on XML in place, were in good shape for whatevers next. Currently, were looking into providing Help kits so customers can bundle help with their own components, including XML doc pulls. Were also looking into automating PDF production for easier printing of Help topics. Inevitably, Microsoft will come out with a new Help system for the .NET Framework and well be in a position to easily support it.
In the long run, wed like to see native-XML rendering, XML Query searches, and dynamic views of the documentation so that you can custom tailor how you want to see the Help. There is tremendous potential with XML. Theres no question in our minds that the technical writing industry as a whole will move over to XML without looking back to format-oriented solutions. So weve put a foundation in place now that we can build on for years to come.
D8 Help Quick Tips
Here are some helpful hints to take better advantage of the new Help system. A lot has changed and the new Help system, at first blush, looks like entirely new territory for a lot of D8 customers.
The D8 Index
We've received feedback of the sort: "Your Help is full of references to VB and says nothing about Delphi. You have no how-to information. In fact, you have no Delphi documentation at all."
This kind of feedback tells us that a lot of Delphi 8 users are by-passing the Borland Help altogether and ending up in the included .NET Framework Help. There are probably two major reasons this happens:
1) The F1 Help. F1 Help will, in many cases, link directly into the .NET Framework Help for relevant API elements.
2) The Help index. The default index filter in the new HTML Help 2.0 (H20) system includes the .NET Framework Help along with third parties integrated into the Borland Help. (Based on the feedback, well look into changing the default to Delphi-only in future releases.)
While there isn't much we can do about F1 calling up .NET Framework Help for relevant .NET API elements, the H20 filter can be changed to focus on Delphi content only in the index.
To change the Index filter to Delphi only:
1. Ensure that the Contents tab appears in the Help window: View | Navigation | Contents.
2. In the Contents frame, select the "Filtered by" drop-down.
3. Choose "Delphi for .NET only"
The index entries will now only contain the relevant entries for Delphi. This will help you focus in on Delphi-specific content. Whats there should get you started in all the major D8 product areas.
What about Delphi 8 code examples?
For D8, Delphi code examples are no longer included in API topics. Heres a detailed explanation why and where to find the alternate location for Delphi-specific code examples (not to be confused with demos) now and in the future.
Building a product on top of the .NET Framework presents us with a major challenge. Given that the Framework includes its own Microsoft-owned documentation for its classes (and much more), how do we give coverage to the Delphi language?
In the past, customers would access Delphi code examples via the Borland API documentation. That route isn't going to work any more because of the .NET Framework. Another problem is that many of the code examples included in the .NET Framework simply aren't necessary when using the Borland code editors, dialogs, and wizards. So how do you tell what you do need to code by hand when looking at the .NET Framework API documentation? Looking in the .NET Framework alone isn't going to help you, even if all the examples were automatically converted to Delphi.
To address these challenges, we built a meta-layer of documentation in the D8 Help system that would include Delphi-specific code examples where required. This layer is the entirely new Procedures section, the How-to guide to D8. It's currently focused on the essentials for D8, but it will certainly grow with your ongoing feedback. This is a fledgling area, so do let us know what How-tos you'd like to see for future releases.
In the past, we've received feedback that critical pieces of information were hidden away in obscure API topics, requiring a needle in the haystack approach to solving problems (the index). We've decided to put those critical pieces of information upfront into the procedures section, which will also cover .NET Framework API usage when relevant. We hope that the new procedures will help you identify those critical pieces of information much faster.
The D8 Table of Contents
Another way to navigate Help content is via the redesigned TOC. We've received feedback in the past that many (most?) customers have stopped using the Delphi TOC altogether due to its complexity (and some say obscurity). This kind of feedback told us that we needed to rework the TOC.
In D8, we redesigned the TOC to be simpler to use, focusing on getting customers up and running fast on the .NET Framework in each major functional area that D8 covers (ECO, Windows Forms, ASP.NET, etc.). Most functional areas include a link to what we think of as the core process for that area, a how-to topic designed to get customers up-to-speed quickly using the technology in question.
For instance, the functional area Building Database Applications with ADO.NET includes core process links to Windows Forms and ASP.NET database procedures (Building a Windows Forms Database Application and Building an ASP.NET Database Application). If Delphi code samples are needed to complete the core process (or other procedures), they are included in the how-to topic itself. You no longer have to search through dozens of API topics for the magic key that unlocks common processes.
Unfortunately, a lot of existing customers are still looking for documentation in old locations. To date, weve probably received the most requests for D8 how-to information and for the updated Delphi Language Guide.
Delphi How-tos
Help path: Borland Help | Delphi 8 for the Microsoft .NET Framework | Procedures
Delphi Language Guide (updated for .NET)
Help path: Borland Help | Delphi 8 for the Microsoft .NET Framework | Reference | Delphi Language Guide
Summary
Do try these tips and give the new Help a chance. We've listened to your feedback and worked hard to solve critical issues with the implementation of the new Help system. We give you our assurance that we will be building on this new foundation and hope that from this document you can see that there are solid innovations to take advantage of today. Though the content structure, production process, and Help engine have changed, the goal is still the same: to provide you with the information you need when you need it.
