Why does the Xojo documentation stink so badly (with example)?

  1. 2 weeks ago

    William K

    Nov 27 Pre-Release Testers, Xojo Pro Chico, CA
    Edited 2 weeks ago

    I don't mean to be completely negativist, but I also don't think that I'm alone with this viewpoint. Ever since the decision was made to move to a wiki format from the old "User's Guide", "Tutorial" and "Language Reference", I've found it almost impossible to find useful information on a topic without knowing some deep-ish link to it first.

    Case in point: I just downloaded and installed the latest Xojo IDE and wanted to do some reading about what it would take to support "Dark Mode" in my cross-platform desktop application. From the Help menu I chose "User Guide", and then typed "Dark Mode" into the Search field. Nothing useful. OK. How about "Supports Dark Mode" (after all that's the caption beside the switch)? Still nothing. Search the "Release Notes" for "dark mode". Oh look, there's mention of an "AppearanceChanged" event. I assume that it's in the Application. Type *that* in. "Sorry your search did not return any results." What about "SupportsDarkMode" all one word, no spaces, just like the release notes say. "Sorry your search did not return any results". WTF.

    This is ridiculous. I shouldn't have to spend more than (at most) 10 seconds to find at least *some* vestige of useful information about some feature that I'm sure took many, many, many, programmer hours to implement. After almost 10 minutes I've given up and decide to write this tirade instead. Did it help me find better information, No. But I feel better.

    DarkMode certainly isn't the feature or concept that isn't easy to find in the new documentation. Pick pretty much any significant programming abstraction and I defy you to easily find a *truly useful* writeup from the "Search" field. I keep the old RB pdf documents around and still refer to them to this day because the new system is so broken. Change my mind.

    - Anonymous

  2. Christian S

    Nov 27 Pre-Release Testers, Xojo Pro, XDC Speakers Germany

    AppearanceChanged finds 3 results here including
    http://docs.xojo.com/Application.AppearanceChanged

    SupportsDarkMode also finds 3 items including
    http://docs.xojo.com/Application.SupportsDarkMode

    dark mode finds 18 items including the user guid entry:
    http://docs.xojo.com/UserGuide:Dark_Mode

    So if there is another problem, maybe fill a feedback case?

  3. William K

    Nov 27 Pre-Release Testers, Xojo Pro Chico, CA
    Edited 2 weeks ago

    Thanks Christian. I see that now, but it's still frustrating that Help > User Guide directs to the Xojo Dev Center (which has the title "User Guide" but doesn't give any useful search results) and Help > Xojo Developer Center *doesn't* actually link to the Dev Center, but instead links to the Xojo documentation. That's much more useful. Cheers.

  4. Christian S

    Nov 27 Pre-Release Testers, Xojo Pro, XDC Speakers Germany

    So we may ask @Paul L to help here.
    e.g. if all content is moved from developer.xojo.com to docs.xojo.com , the old page could be changed to redirect to new page.
    Or the search in one site should find entries for both sites.

  5. Joost R

    Nov 27 Pre-Release Testers, Xojo Pro The Netherlands

    @WilliamKoperwhats - compared to technical documentation for many other platforms and tools, Xojo docu is incredibly good. @Paul L does an excellent job and thanks to him many newbies find their way out easily in Xojo.

  6. William K

    Nov 27 Pre-Release Testers, Xojo Pro Chico, CA

    Joost, I'm not necessarily complaining about how accurate the documentation is, just how difficult it is to find things. Not only is the help menu (where most newcomers will turn to find basic information) confusing, even if you happen to pick the right starting point (like docs.xojo.com ), there's no guarantee that you'll stay there.

    Searching for "Dark Mode" on docs.xojo.com leads to a useful write up, but the header (green box) says that it's in the "Users Guide". Clicking on the "Users Guide" in the sidebar takes you completely out of the docs back into the Dev Center where you'll fine absolutely nothing useful and no obvious way of getting back to the original site.

    Christian, you insinuated that the "developer" site is old, and the "docs" site is newer. That's certainly not obvious, and, if true is an incredibly important distinction that needs to be made.

  7. Derk J

    Nov 28 Pre-Release Testers, Xojo Pro

    You can make a feedback report about parts of documentation missing or wrongly typed etc.

  8. Emile S

    Nov 28 Europe (France, Strasbourg)

    I took DataBaseRecord example lately, modify it to fit my needs and it never was working…

    until:
    I close the internet connection (WiFi),
    Power Off the computer,
    Drink a cup of coffe (around noon).

    Reboot, added a Commit, and some more lines…

    And then, all of a suffen, it started to work.

    I go home, still off line, removed the added lines, it started to work.

    I wanted to make a report, but it is still working… and don’t ask me why.

    Xojo 2015r1
    El Capitan
    MacBook Pro 13" (4 y/o).

  9. Beatrix W

    Nov 28 Pre-Release Testers Europe (Germany)

    When in doubt use the Goggle.

    The documentation from Xojo - in spite of the total sillyness of having 2 documentations - is better than the one from Christian (thin) and Valentina (barely understandable russian english).

  10. Alberto D

    Nov 28 Pre-Release Testers, Xojo Pro

    Recently they changed to a new docs.xojo site, also, they are moving some information from developer.xojo to docs.xojo. This things take time to completely finish.

    Anything (everything?) could be better and better differs from one person to another.

  11. Paul L

    Nov 28 Xojo Inc http://docs.xojo.com
    Edited 2 weeks ago

    @WilliamKoperwhats Searching for "Dark Mode" on docs.xojo.com leads to a useful write up, but the header (green box) says that it's in the "Users Guide". Clicking on the "Users Guide" in the sidebar takes you completely out of the docs back into the Dev Center where you'll fine absolutely nothing useful and no obvious way of getting back to the original site.

    I'm sorry you had trouble finding this info, I hope it will be better in the future.

    The User Guide is in the process of being updated and moved over to the wiki (https://docs.xojo.com ). so that everything is in one location. We are talking about 1000s of pages of docs though, so this is not going to happen instantly.

    As content is moved it appears in the User Guide category and there are already many pages available: https://docs.xojo.com/Category:User_Guide

    Edit: Fixed typo in URL

  12. Sascha S

    Nov 28 Pre-Release Testers, Xojo Pro Germany

    @Paul L [url=(http;//docs.xojo.com](http;//docs.xojo.com[/url])

    On Windows Chrome this leads to a white "about:blank" page. ;)

  13. Alberto D

    Nov 28 Pre-Release Testers, Xojo Pro

    @SaschaSchneppmueller On Windows Chrome this leads to a white "about:blank" page. ;)

    Is hard to type : with one finger ;)

  14. Eduardo G

    Nov 28 Pre-Release Testers Europe (Madrid, Spain)

    @Beatrix W When in doubt use the Goggle.

    This. Xojo documentation is excelent. The failure point is the search engine. I use it constantly, but I never search in it (other than direct access from right-clicking the user guide).

  15. Björn E

    Nov 28 Pre-Release Testers, Xojo Pro Iceland

    I think it is mostly the double documentation that makes no sense. And I tend to always get the old one when I don't want the old one and then the few times I get something else then I to often get broken links.

    Other than that then I think the content in the documentation is usually not bad.

  16. Art G

    Nov 28 Prescott AZ

    My only complaint is that it now takes more clicks to get the info you want. Method definitions and examples used to be on the same page as the class.

  17. Tim S

    Nov 28 Canterbury, UK

    How do I make a documentation change request? Fora new Feedback case, there appear to be (a) Bug and (b) Feature request, categories, only.

    Also: if the two sets of doc are going to be merged, that is a good thing (obvs). But the new and now largely gone developer doc set did have a nice feedback feature at the bottom of each page. This allowed me to comment on and request additions to a specific page (or mention typos etc). Could we have this on the final doc set?

    In general the pages are too often incomplete at the detail level. For example, although it says I can make a zero length memoryblock, there is some doubt about whether I can successfully set LittleEndian=false for such a memoryblock, at least before I've put some data in it. Further, if I have:

    Dim  aa, bb as memoryblock
    aa = new memoryblock (20)
    aa.LittleEndian = false
    bb = aa

    Now, after some testing it seems that I then have to set the LittleEndian property for bb - separately. This is not mentioned.

  18. Dave S

    Nov 28 San Diego, California USA

    @Tim S How do I make a documentation change request?

    I don't know if the is the "right" way, or if he would prefer people did not do it this way... .but I've in the past just sent them directly to Paul Lefebvre

  19. Tim S

    Nov 28 Canterbury, UK

    @Dave S I don't know if the is the "right" way, or if he would prefer people did not do it this way... .but I've in the past just sent them directly to Paul Lefebvre

    Well yes, and after using the bottom-of-page feedback method, I've had a couple of exchanges with Paul too. However I don't know whether Paul is "Mr Documentation" or "Mr In-charge-of-documentation". I'm happy to use whatever suits Xojo best and to make hopefully useful doc change suggestions.

  20. Paul L

    Nov 28 Xojo Inc http://docs.xojo.com

    The bottom of every page at docs.xojo.com has a "Send Doc Feedback" link to this page: https://docs.xojo.com/Xojo_Documentation:Leave_Feedback

    Essentially, an email to docs@xojo.com is fine for most things. Feedback works as well, so whatever is most convenient for you is fine with me.

  21. Newer ›

or Sign Up to reply!