Documentation suggestions

Documentation suggestions

In the "Introductions" thread, Jim discussed some of the problems he ran intowith the AV documentation. See http://softwareforums.intel.com/ids/board/message?board.id=Visualizer&message.id=7.

Jim is heavy user of the AvObjMod module and finds it is not easy to know how to obtain the object handle used by each of the AvObjMod routines. I guess in languages like JavaScript or VB this is a little more intuitive since objects, sub-objects, and methods are connected via the "dot" operator. For example to adjust the positionof the camera belonging to graph "foo" you would have the following in JavaScript:
Code:

root.Graphs.Item("foo").Camera.Viewpoint(AV_XCOORD) = 3.12;
root.Graphs.Item("foo").Camera.Viewpoint(AV_YCOORD) = 1.28;
root.Graphs.Item("foo").Camera.Viewpoint(AV_ZCOORD) = 1.41;

Here "root" is the reference to the top Group instance. A more efficient way to code this would be to first get the reference to the camera and then set the viewpoint:

Code:

var hCamera = root.Graphs.Item("foo").Camera;
hCamera.Viewpoint(AV_XCOORD) = 3.12;
hCamera.Viewpoint(AV_YCOORD) = 1.28;
hCamera.Viewpoint(AV_ZCOORD) = 1.41;

But anyway, since Fortran doesn't support this type of syntax, the code to do the same thing in Fortran looks a bit different:
Code:

hGraphs = avGraphs(hRoot)
hGraph = avItem(hGraphs, "foo")
hCamera = avCamera(hGraph)
call avSetViewpoint(hCamera, (/1.5_8, 1.9_8, 0.6_8/), status)

Or we can nest the object reference calls to do everything in one line:
Code:

call avSetViewpoint(avCamera(avItem(avGraphs(hRoot), "foo"))

So instead of working our from the top down: root.graphs.camera, we go from the bottom up: camera(graphs(hRoot)).

Now thinking about this from the documentation point of view, one thing I think we should really have is for all the AvObjMod routines and functions to be in the help index. Given that, typing avSetViewPoint would take you to the Viewpoint property page of the camera object. Wouldn't that go a long way in helping what object reference to use? It might help more if when you went to the camera object in the help, it gave you some hints on how to get a reference to a camera. I'm just thinking that updating the syntax for each property/method for each object would be overkill.

Something else that might help is printing out a copy of the object heirarchy diagram. It's in the help; I've also attached it here. The diagram should help you navigate up and down the object model.

Something else that I think would helpis a series of tutorials on using AV. I'm hoping to might some progress on that front this year. I might post these to the forum to get feedback before incorporating them in the help proper.

Message Edited by jlreadey on 10-16-2005 07:13 PM

6 posts / 0 new
Last post
For more complete information about compiler optimizations, see our Optimization Notice.

I forgot to attach the diagram. Here it is...

>> Given that, typing avSetViewPoint would take you to the Viewpoint property page of the camera object. Wouldn't that go a long way in helping what object reference to use?
<<

The problem is finding the object handle. The examples you gave in the enclosed boxes are exactly what is needed.

Even showing the .js line would help

root.Graphs.Item("foo").Camera.Viewpoint(AV_XCOORD) = 3.12;

But for the documentation that ships as a feature of FORTRAN it would make sense to illustrate using FORTRAN calls as well. (and not as an afterthought)

Even your documentation showing use with C++ (and other object model programs) is skimpy

oCamera.Viewpoint(...)

because it does not illustrate where and how the camera object comes from.

The software developer that wrote the code is the last person that should be used to document the code. Because what they know well is what is documented least. The document should be and extraction of that knowledge such that it can be passed on to the ignorant. i.e. the documentation must be a learning tool and not a reminder tool.

>>I'm just thinking that updating the syntax for each property/method for each object would be overkill.<<

Precisely what I mean. The programmer in you is telling you it is an overkill. To the person trying to learn what you know of AV it is exactly what they need.

Try to look at this from the newbie's point of view.

Thanks for taking the time to make a good topic in this forum.

Jim Dempsey

As an example of better documentation let's consider avCreatePlot:

The copy of the documentation I have contains:
------------------------
CreatePlot Method
[Applies To]

This method creates a plot of the specified type.

Javascript syntax
object.CreatePlot(name, plotType)

Visual Basic syntax
Function CreatePlot(ByVal name As String, ByVal plotType As Avis.Objmod.AvPlotType) As Object

C# syntax
System.Object CreatePlot( System.String name, Avis.Objmod.AvPlotType plotType )

C++ syntax
HRESULT CreatePlot(
BSTR name,
AvPlotType plotType,
LPDISPATCH *pItem
);

Fortran syntax
subroutine avCreatePlot(object, name, plottype, item)
integer(int_ptr_kind()), intent(IN) :: object
character(*), intent(IN) :: name
integer, intent(IN) :: plottype
integer(int_ptr_kind()), intent(OUT) :: item
end subroutine avCreatePlot

-------------

Where:

"AvPlotType" is a hyperlink, which is and example of a good documentation technique, to a pop-up that lists the enum for AvPlotType. Unfortunately in the FORTRAN description the "plottype" is not similarly hyperlinked to the same enum for AvPlotType. The user must figure out that maybe the Fortran plottype is the same as the C++ AvPlotType. This isn't too far of a stretch. And I suppose you could say "If he is too dumb to figure that out then why is he programming?". Where the point to make is the inverse of that "If the techwriter is to lazy to insert a hyperlink where it belongs then why is he techwriting?".

Now let's critique the rest of this example.

The Javascript syntax has object.CreatePlot..., VB has Avis.Objmod.AvPlotType, C# has System.Object CreatePlot, C++ has HRESULT CreatePlot.

The C++ must be a typeo because it should either be pIPlots->CreatePlot(... or g_RootObj.CreatePlot(... to be consistent with the rest of the documentation.

Now here is the gripe. You do have an [Applies To] which leads you to AvPlots collection and indirectly implies that perhaps object is an AvPlots collection. Now the reader must figure out if this is so and then how to get the handle to the AvPlots collection.

What would be better would be if (for the FORTRAN example) you replace "object" with "hPlots" which is not an AV object but an intuitive handle inferring a handle to "Plots". Then make hPlots hyperlinked but not to the deffinition of AvPlots but to a short description of function calls that can be used to obtain the AvPlots handle using various different methods and with notes of usage, sample code etc.... Call this the object extraction page. You need only to write this section once (and maintain it in this one place) and it would be accessible by every function so linked to hPlots.

For some functions the may be one of a group of objects. For this you could continue to use "object" or to be consistent "hObject" but instead of remaining opaque have hObject link to a list of objects that usable for this function (the link could be further down on the same page or on a seperate page). Each item in the list of applicable objects is then hyperlinked to the object extraction page.

In some of your function calls you have "path" of "objpath". objpath is linked to a good description (with chart) of the object path. The gripe is some of the function calls that take an objpath also take additional arguments. These are not identifi
ed in the topic explaining the function call using path/objpath. The user becomes aware of this only if they accidentally come across an example using the options.

This should get you started on making a better document. Later we can discuss larger scoped issues.

Jim Dempsey

Thanks for the detailed suggestions on how to improve the documentation. I agree that it's not very easy for the developers who wrotethe code to appreciate the difficulties of someone learning to use the product. In order to better understand theses issues we recentlyorganized a usability study of AV.We had a small group of people who were unfamiliar with the product go through a list of simple tasks and noted the problems they ran into. Needless to say, the group ran into a lot of problems in both the Viewer user interface and the documentation that we hadn't realized where serious stumbling blocks before. This study focused on Viewer usability. Next time perhaps we'll try out some development tasks and see how that goes.

Anyway, I encourage everyone to contribute their suggestions for improving the documentation by posting to this thread. Joan Buchanan, the technical writer for AV has promised that she'll post her thoughts here in a day or so.

Hi,

I will work with John to see what improvements we can make in the documentation. Thank you for the feedback!

Leave a Comment

Please sign in to add a comment. Not a member? Join today