There are three primary pieces to help; the help viewer, the action of invoking the help from the IDE, and the glue between the IDE and the help viewer. If you press F1 and don't get help, is the IDE failing, is the content not written, delivered or found, or is the glue between the IDE and help viewer failing?
Testing is one of the most difficult tasks of the documentation process. As is typical with testing, more can always be done. Currently we have tests that test pressing F1 on all the components, all the properties and events of each component in the object inspector, errors, messages and warnings in the compiler message view and most dialogs. Each page that is displayed is tested to see if the title is what was expected to hopefully provide more accuracy to the content. I say "hopefully" because there really is no guarantee without sitting a human down and having them press the F1 key and read the content that is displayed in the help viewer. What we are looking for here is do we get a reasonable page.
But what makes our reference documentation so difficult to test is sometimes you really don't get the page that you expect. For example, create a default application with the following:
type
TForm1 = class(TForm)
end;
If you press F1 with your cursor over TForm1 you will still get help even though it is a class only defined in your application. The help will be for TForm. I'll discuss more about this in Part IV, but depending on where you are in the IDE the RTTI and compiler are used in conjunction with the help function ContainsHelpKeyword. So the results when you press F1 may vary. Well, they won't once the help is locked down and isn’t changing, but while the help is being written they may vary.
I have also been working on a unit test for interaction between the help viewer and the IDE for testing the glue code that binds the two. This test consists of the help code in the IDE as a stand-alone application that can interact with the help viewer. Given a list of keywords and context IDs we can inspect the help to make sure those individual pages are present in the build help. This also allows us to test a help build quickly without loading the IDE to make sure our changes worked or not.
Also for obvious reasons we rely on humans to make sure the content is accurate. Kudos to all you field testers and developers out there using Delphi. Thank you for all your bug reports!
Part I
Part II
Part III
Part IV
No comments:
Post a Comment