[CONNECT APIs] Documentation Improvement Requested

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¢.

Parents
  • 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) :).

    1. MicroStation CONNECT Edition SDK Update 5 will include a number of Developer Shell Search and Navigation improvements.  The new SDKSEARCH script provides you from the convenience of your developer shell to search across all these (standard/common) SDK specific resources:
      1. Search standard SDK Text folders
        1. MigrationTools (I am migrating what should I use...)
        2. Examples (Now I need to see if something exists...)
        3. Includes (Now I need to implement... [headers and make includes])
      2. Search standard SDK Binary folders ("quick" search)
        1. Libraries folder (what possible library/libraries do I need to link with)
        2. Assemblies folder (what possible classes do I need to reference)
      3. Search SDK specific (web) Community (Optional: Y/N)
        1. Continue the same (wildcard) search on the SDK specific community (results ordered by date time most recent first, then by relevance)
    2. Search Ninja.  Please note the following is my own personal preference based on my experiences and do not reflect any known current and defacto standards or "best practices"; though I apply these techniques daily.  Staying on top of change can certainly be challenging.  Identifying exactly what, where, and a proper format for achieving the right amount of high to low level training needed, vs. simply finding exactly what you need, following by (good) example; within a reasonable and productive amount of time tends to be a balance we all may struggle with and try to achieve. I gravitate to search; be it: desktop search, object browser, help files, web, enterprise, then local (findstr/grep) primarily in that order due to the relative speed and capability benefits achieved.  I will focus on what I like and use effectively with CHM help files to keep this short.
    • Exercise:
    • Let's try an example of searching for EC Class with a couple techniques:
    • Index Tab, TYPE: EC Class, RESULTS = 0
    • Search Tab, TYPE: EC Class, RESULTS = 62
    • Search Tab, TYPE: "EC Class", RESULTS = 1
    • NOTES:
    • We attempted a loose search for "EC Class" vs. "ECClass" to help illustrate a point.  We can search on topics vs exact names to give us hints on those specific areas we are new to or have interest in learning more.  We can go on to use additional "loose" (similar or wildcard) word searches and Boolean operators to filter for very precise results not knowing too much on our way into a given topic or question we have.

    • CHM help files with search tabs - are the best.  Take careful note of a couple items on the search tab to get the most effective results
      • Quoted searches.  If you don't use quotes it is like searching for A OR B, where using quotes allows you to search for items with literal spaces: "A B"
      • Wildcard searches.  Try searching for random topics you may bump into on occasion; like: mdlCell*, DgnEC*, *ECObj*
      • Search Tab "Expansion Arrow" (right side next to text search field).  Lists a number of (case-sensitive) effective Boolean operator to tilter results with: AND, OR, NEAR, NOT.  Use these effectively to narrow down your search results to something more specific to your needs.  Example 1 (use one or more logical/boolean operators): ECClass AND element, Example 2 (you can use quotes too): ECClass AND element AND "Item Types"
      • Search Result in page highlighting.  Very helpful on large pages or pages with many results allowing you to quickly scan over a page until you see a term highlighting.
      • Pay close attention to the bottom of the search tab, don't overlook a couple other (pesky or important?) items:
        • Search previous results.  Personally I would use Boolean filters first before going all the way down here to check this box, but can give similar results.
        • Match similar words.  This can help provide additional results for words that may be very similar that your wildcard searches may (or may not) provide you.  Depending on how common the search term is you are looking for you may choose to uncheck this until needed.
      • Lastly, if the CHM help file is built with all helpful options, once you find that hard find page:
        • #1 - Bookmark the help topic (rename if you like) knowing it save to a ".CHW" file in the same directory as the parent .CHM help file.  If you frequent a page often this can be very helpful.
        • #2 - Check to see if the CHM file provides a "Locate" button in the top toolbar.  If so, this can help you navigate to where that hard to find topic is located in large help documents and provides you with another way to communicate to others on how to navigate.
        • TIP:  If you like, you can actually Right-click > Properties on any given or favorite page/help topic, go to the Address (URL) field, Triple click the text item's location, then save that to your own documentation, shortcuts, or Internet Browser Favorites.

    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! 

  • 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

  • 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 :-(

    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).

    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

  • 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 

  • 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.

     
    Regards, Jon Summers
    LA Solutions

Reply
  • 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.

     
    Regards, Jon Summers
    LA Solutions

Children
No Data