Documentation API1 vs API2 Rant

  1. ‹ Older
  2. 3 weeks ago

    Thomas R

    Jun 19 Europe, France, Besancon

    Did I miss something? What's the difference with SortWith since API2 ?

  3. Paul L

    Jun 19 Xojo Inc, Third Party Store

    You did not miss anything. SortWith did not change for API 2.0.

  4. Geoff P

    Jun 19 Xojo Inc Austin, Texas

    @Tim P It used to be possible to figure these things out from the doc history, but they disabled history and I've completely exhausted the MVPs trying to explain how important this is.

    Everyone loses this way. Xojo has to give a bad "use the local docs" answer, and you're stuck lost and confused.

    The local language reference will always be the easiest and fastest way to know what is available for the version of Xojo you are using. The online reference was always intended to be the latest version and not an archive of all past versions of the documentation. It being in a wiki happens to provide that but we are increasingly frustrated with the wiki as a documentation delivery tool. It is unsurprising that it's not commonly used for this purpose. Most documentation I have found is in straight HTML format.

  5. nicolás c

    Jun 21 Xojo Pro

    maybe xojo could use the same approach as postgresql docs has.

  6. Jay M

    Jun 22 Testers, Xojo Pro 30.3668397,-97.7399123

    @Geoff P We don't mark what is API 1 or API 2.

    What is the downside of marking the docs to reflect the version?

  7. Jay M

    Jun 22 Testers, Xojo Pro 30.3668397,-97.7399123
    Edited 3 weeks ago

    @Paul L You did not miss anything. SortWith did not change for API 2.0.

    I'm sorry Paul I wasn't exactly clear here.
    I have never used sortwith before.
    So whether it changed or not is not material to my question. I was left trying to figure out whether or not it was API1 OR API2 On my own.

    This meant that I had to test it in API one and an API two to figure out that it was both. 15 minutes of my life that could have been solved by simply glancing up and seeing Which version of Xojo it applied to.

  8. Karen A

    Jun 22 Testers
    Edited 3 weeks ago

    @Jay M So whether it changed or not is not material to my question. I was left trying to figure out whether or not it was API1 OR API2 On my own.

    Did not change means it is not specific to API 1 or 2 , but common to both.

    While it might seem like it, API 2 did not change everything and (AFAIK) was not meant to change everything.

    If something is depreciated it is API 1 ONLY.

    -karen

  9. Paul L

    Jun 22 Xojo Inc, Third Party Store

    @Jay M I'm sorry Paul I wasn't exactly clear here.
    I have never used sortwith before.
    So whether it changed or not is not material to my question. I was left trying to figure out whether or not it was API1 OR API2 On my own.

    This meant that I had to test it in API one and an API two to figure out that it was both. 15 minutes of my life that could have been solved by simply glancing up and seeing Which version of Xojo it applied to.

    I believe I addressed this above. If an item is API 2.0 then it has the API 2.0 category and also likely shows the specific version it was added.

    If it does not have those things then it is API 1 and nearly all API 1 stuff continues to work same as before.

  10. Tim J

    Jun 22 Testers, Xojo Pro N. Phoenix, AZ
    Edited 3 weeks ago

    @Geoff P The local language reference will always be the easiest and fastest way to know what is available for the version of Xojo you are using

    Except that quite often a link in the local copy takes you to the online copy. See Feedback Case #57973 and wonder at the way it was simply closed ...

  11. 2 weeks ago

    Beatrix W

    Jun 23 Testers, Third Party Store Europe (Germany)

    The local help would be good if it actually worked.

    I need to check an event. Name doesn't matter. Let's try "keydown". I click on canvas.keydown: everything is okay. I click on checkbox.keydown: nothing happens. Some classes work and others don't. Bug or feature?

    Xojo 2019r3 on High Sierra.

  12. Paul L

    Jun 23 Xojo Inc, Third Party Store

    @Beatrix W I need to check an event. Name doesn't matter. Let's try "keydown". I click on canvas.keydown: everything is okay. I click on checkbox.keydown: nothing happens. Some classes work and others don't. Bug or feature?

    Most controls get their KeyDown event from RectControl, so if you click on Canvas.KeyDown or CheckBox.KeyDown it will show the RectControl.KeyDown doc page. This is how the docs have always worked, both local and online.

  13. Sascha S

    Jun 23 Testers, Xojo Pro Germany, Lower Saxony
    Edited 2 weeks ago

    @Beatrix W Some classes work and others don't.

    @Paul L This is how the docs have always worked, ...

    Sorry @Paul L but i could not resist. ;)

  14. Tim J

    Jun 23 Testers, Xojo Pro N. Phoenix, AZ

    @SaschaSchneppmueller Sorry @Paul L but i could not resist. ;)

    You did that tongue-in-cheek, but it's too true to be funny.

    I will restate in simpler terms the gist of my feedback report above -

    If a user selected the Local documentation, NOTHING that you search for in the local docs should refer that user to the online docs.

  15. Norman P

    Jun 23 Testers, Xojo Pro outside admiring the sunshine,...

    @Tim J If a user selected the Local documentation, NOTHING that you search for in the local docs should refer that user to the online docs.

    I'd agree
    The tool I wrote that generated the local set from the wiki got a pile of updates to find and fix those issues as they were reported
    There are/were still some spots where links were embedded in unusual ways that it missed
    Obviously there still are

  16. Paul L

    Jun 23 Xojo Inc, Third Party Store

    @Tim J If a user selected the Local documentation, NOTHING that you search for in the local docs should refer that user to the online docs.

    Why not? What if you are using the local doc viewer but also have internet access? Would it not be helpful to have a local doc page with an external link that takes you to related (such as User Guide) content? Or are there other situations where it is linking to the wrong things? I didn't notice specific examples when I went back to review your case.

    Can you clarify your statement?

  17. Karen A

    Jun 23 Testers

    @Paul L Why not?

    Because the user CHOSE to use the local docs even if they do have a net connection maybe?

    There is the whole API 1-2 thing and changes between Xojo versions. If you are not using the current Xojo version getting directed to the online docs can easily cause confusion... PARTICULARLY if one selected local to avoid such issues.

    -Karen

  18. Tim J

    Jun 24 Testers, Xojo Pro N. Phoenix, AZ

    @Paul L Can you clarify your statement?

    You're being obtuse and argumentative, right? Why would I want the 18r3 docs take me to the updated online 19r3.1 version of the User Guide?

    As for my case - specific situations are not of importance - even though I mentioned the IDE Scripting in the report. Just remove all of the external links from the local docs and make sure that anything needed is included in the local copy.

  19. Paul L

    Jun 24 Xojo Inc, Third Party Store

    @Tim J You're being obtuse and argumentative, right?

    Well, no. But I do find this comment to be rude and insulting. Keep your tone civil, please.

    @Tim J Why would I want the 18r3 docs take me to the updated online 19r3.1 version of the User Guide?

    OK, so if you are using a non-current release then you don't want to go to do the online docs. Not sure I got that from your other comments. Seems like someone using a current release would benefit from having links that go online, though.

    @Tim J As for my case - specific situations are not of importance - even though I mentioned the IDE Scripting in the report. Just remove all of the external links from the local docs and make sure that anything needed is included in the local copy.

    Understanding specific situations is important. Just because this behavior change is what you want does not mean it is what makes sense for everyone. Create a Feedback feature request and we will discuss on our end to see what is feasible.

  20. Tim J

    Jun 24 Testers, Xojo Pro N. Phoenix, AZ

    @Paul L OK, so if you are using a non-current release then you don't want to go to do the online docs. Not sure I got that from your other comments. Seems like someone using a current release would benefit from having links that go online, though.

    No - if I set it to use local - I only want it to use the local docs. Maybe I'm on a metered connection and don't want to eat my bandwidth looking for information that was represented as being available locally. The option doesn't ask if I want to access SOME of the docs locally.

    I never said it made sense for everyone - when I post a feedback report or feature request, I do so because it affects me. however, I am confused as how you could possibly assume that this one COULDN'T affect everyone.

or Sign Up to reply!