The current API documentation (MicroStation CONNECT Update4) makes it hard to find things. In particular, topic overview descriptions that introduce a part of the API do not make themselves known. Here's an example: in their answers to a question, Bob Hook and Paul Connelly mentioned Linear Transformations: RotMatrix, Transform, DMatrix4d, DMap4d in the MicroStationAPI. The RotMatrix class is a 21st-century replacement for the mdlRMatrix_ family of C-style functions.
In two years of using the MicroStationAPI, I had not noticed either the RotMatrix class or its introductory topic Linear Transformations. Even now, knowing that it exists, it's hard to find it in the documentation. Yes, if you know the topic title letter-for-letter you can find it — but if you search help for, say, Linear Transforms that topic is not included among the search results.
This is a catch-22 situation: if you know exactly what you're looking for, you can find it; but, if you don't know exactly what you're seeking you can't find it. But the reason for using help documentation is to find things about which we are unsure. Help doesn't help when we most need it.
The API documentation is generated automatically from source code. It uses a form of markup unique, as far as I know, to Bentley Systems. It needs development. For example, overview topics such as Linear Transformations or Layout Manager Introduction should bubble to the top level of help contents, perhaps in their own Overview chapter.
Here's another example: suppose I want information about ECClass. If I know the exact class name, then a search succeeds. Well, sort of. The first few hits for that search are ECSchema.h Source File, Member List, Member List, ECClass Struct Reference, Class Members,Class Members - Functions …. There's a lot of noise in that search result. I would prefer to see some sort of overview rather than a link to the header file. But what happens if I search for something not perfectly accurate, such as EC Class? I see Class Hierarchy, Class List, Bentley::DgnPlatform Namespace Reference … again not too helpful for the person seeking enlightenment rather than obfuscation. Of course, the help system is hampered by its format: Microsoft .CHM help doesn't do fuzzy searches.
Well, I've got that off my chest: just my 2¢.
Hi Jon,
There are two (indirect) items currently in progress to certainly help all of us with searching, isolating, and identifying correct information across various sources. Please bear with me for a moment on #1 to understand the problems soon to be addressed in Update 5, then on to #2 a bit of "Search Ninja" (CHM searching - though I don't expect the masses to convert immediately, and why I sort-of really like and thrive on searching) :).
Hopefully with some of the above Search Ninja (CHM edition - but a lot applies to most other search sources mentioned with subtle variances) you can slice and dice to some exact search results you need more effectively.
Outside of the underlying needs to for more effective SDK searching hopefully discussed and addressed above, I will file an enhancement request to review each API section for having a a.) sufficient Overview help topic and b.) ensure each help topic is also listed in the Index and Search results tabs to make sure items can be found more consistently and readily.
UPDATE (RH 05/03/2017) Enhancement 695481 was filed to help improve the SDK documentation items requested.
Please let us know of other ideas you may have that we can apply towards improving our SDKs.Every journey starts with a first step. Chances are if you find value in something others will too.
HTH and have a good day!Bob
Answer Verified By: Jon Summers
Jon - my issue with the help documentation is that it is more of an outline. It really does not help in the Connect version. if i want better help i have to go back to v8.
Here is an example. I'm looking for how to use the DialogBoxRsc and this is all it gives me. Am i reading it incorrectly? I don't think so. At least in v8 it would give me some explanation of the fields.
Someone please help!
Steven Watson said:My issue with the help documentation is that if i want better help i have to go back to v8
That works to a limited extent. For MDL functions the V8 help is better: but many function signatures have changed in the move from 32-bit V8 to 64-bit CONNECT.
There are many classes in CONNECT that don't exist in the V8 MDL libraries.
Regards, Jon Summers LA Solutions
Steven Watson said: It really does not help in the Connect version.
It depends. Generally, CE C++ help is better than V8i in my opinion. Often it is (at least) 1:1 transition, with necessary modifications mentioned by Jon, but sometimes the description is better. But, there are exceptions :-(
Steven Watson said:I'm looking for how to use the DialogBoxRsc and this is all it gives me. Am i reading it incorrectly?
It is the exception when CE doc is not worse, but it is not at all. For some reasons, sometimes the description is missing (I also found in the past a few of similar, I guess always related to MicroStation resources).
Steven Watson said:Someone please help!
I think the only help is to report every individual missing description (that exists in V8i and exists in CE API) here and to hope somebody responsible for documentation fix it. General discussions how doc is bad do not help, because they do not provide any hint what should be fixed ;-)
Regards,
Jan
Bentley Accredited Developer: iTwin Platform - AssociateLabyrinth Technology | dev.notes() | cad.point
Guess my other question is how is this possible with a software of this magnitude? You would expect world class documentation from a world class software package.
don’t get me wrong and I’m not giving up on it but it is so frustrating that we can’t just go to the help to figure out the code context.
it is also great that we have this forum to discuss things too. Thanks for understanding
Steven Watson said:we can’t just go to the help to figure out the code context
While I agree with that sentiment, one of the best ways to illustrate an API is to provide examples. Bentley Systems deliver some examples when you install the MicroStation SDK. However, the examples don't cover all of the SDK (how could they, with thousands of functions and classes?) and leave gaps for many useful idioms.
I've written some examples to augment those in the SDK, but you have to treat them cautiously. I don't necessarily use the correct API to solve a particular task, I don't necessarily understand the API precisely, and I may have ignored a better alternative. Plus, we can't all be experts on everything: I've written no code that covers visualisation or materials and I defer to Jan on his knowledge of EC Schemas.