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

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

AppearanceChanged finds 3 results here including
http://documentation.xojo.com/api/deprecated/application.html#application-appearancechanged

SupportsDarkMode also finds 3 items including
http://documentation.xojo.com/api/language/app.htmllication.SupportsDarkMode

dark mode finds 18 items including the user guid entry:
http://documentation.xojo.com/topics/user_interface/desktop/macos/supporting_macos_dark_mode.html

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

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.

So we may ask @Paul Lefebvre to help here.
e.g. if all content is moved from developer.xojo.com to documentation.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.

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

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 documentation.xojo.com), there’s no guarantee that you’ll stay there.

Searching for “Dark Mode” on documentation.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.

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

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

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

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.

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://documentation.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://documentation.xojo.com/Category:User_Guide

Edit: Fixed typo in URL

On Windows Chrome this leads to a white “about:blank” page. :wink:

Is hard to type : with one finger :wink:

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

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.

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.

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.

[quote=416017:@Tim Streater]
How do I make a documentation change request?[/quote]

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.

The bottom of every page at documentation.xojo.com has a “Send Doc Feedback” link to this page: https://documentation.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.