Xojo has a big API and it’s impossible to know everything. This is made even more impossible since Xojo gets updated three to four times a year and, in the past couple of years, they’ve added two new targets (iOS and Raspberry Pi) and a new framework that is going to be used more in the future.
Despite my nearly sixteen years of constant usage I find myself struggling, at times, to find things in the Xojo documentation. Don’t get me wrong, I can usually guess at the right location but I think discoverability in Xojo is lacking. I think this hurts all developers, not just those new to Xojo.
Local Language Reference: This was rewritten a few years ago and is very reminiscent of the popular documentation tool Dash. It starts with a basic landing instruction page along with the overall list of ‘sections’ and the user can either drill down in the list or use the single search field to filter the list.
The nice thing about it is that it’s fast. Type in ‘Record’ and you’ll quickly get every entry that has record in the name (it’s a lot, by the way). Each entry has a blurb on what it does, a listing of the Events, Properties, and Methods. You can click on any of these and you’ll be taken to the page for that particular item. Many entries have a notes section and example section.
Perhaps more importantly, some entries have See Also information. For example, the Recordset class entry can take you to the Database Class, DatabaseField, Database Record, etc. All things an average developer might eventually want to know in relation to databases.
What what I’ve gathered the local Language Reference is simply an extract of the wiki (below) and put into a database that the IDE accesses.
http://docs.xojo.com (the Wiki): If you’re not using the local Language Reference, you’ll be taken to the online Wiki hosted by Xojo. As far as I can tell this is exactly the same information as the local Language Reference, just shown in a web browser (or HTMLViewer if you’re using a Xojo window). This is handy for providing links to the documentation for people in the Forums, because yes, sometimes people don’t know about the Wiki.
Since it’s essentially the same as the local Language Reference it’s only real advantage is that it can be updated without a new Xojo release. The drawback, of course, is that you need an internet connection and because of this, and speed, I prefer the local version.
There were also some contributors to the wiki. If you look at http://docs.xojo.com/index.php/Special:ListUsers you’ll see the people that could modify the wiki. I’m not sure how much this was used but I feel that this should be an important factor in documentation. And because it’s a wiki, is there anything stopping someone from hosting a copy of this and modifying it?
http://developer.xojo.com (Xojo Dev Center): The first impression is that it’s a cleaner look since it uses a large font, has ample spacing, etc.. You have the option to save the page or the entire site as a PDF document. All of the new Xojo framework is in this format so I suspect this might be the format of the future.
Find Xojo.Crypto, for example, and the page lists a summary of the class. It lists the Enumerations, methods, related classes, platforms and project types supported, lists example projects and any related classes. Click on any of those items and you’ll be taken to the section describing it in more detail
I don’t find the new documentation all that useful. Everything about that class is in one large page rather than individual pages. It gives the documentation a cluttered and hard-to-use feel. A great example of this is selecting one of the methods and having the entire page scroll to the method. Hitting the browser back button does not take you back to the top like I expect so I’m forced to manually scroll to the top. Not exception onerous, mind you, but harder to use than it should be, in my opinion.
I also find the notes and example sections far less complete than what I would like. And since there’s no way to add my own notes to the documentation the only option I have is to created a Feedback report to get it changed.
Creating a feedback report isn’t a great solution. There’s the right and proper way to use classes and then there are edge cases that are how real-world developers might use them. This is where the ability to ask a question and then have contributors and/or Xojo engineers answer them is helpful.
To the best of my knowledge there is no way for the community to add or modify this content. This does the experts in the community a disservice since there are times when we could add helpful information. To do this now, we need to submit a Feedback report.
New Project Pane in the IDE: The Xojo Examples directory is chock full of examples. Some better than others. Create a new project in the IDE and look at the Examples section. There are hundreds of projects to choose from but finding them is difficult. Sure, I can sometimes guess where something is, but should it not be easier? If I’m looking for FolderItem examples it sure would be nice to search for FolderItem and show me all projects that use it. It’s a common class and I’d like to see all the examples that use it.
I found something in iOS quite by accident last week when I decided to peruse the iOS projects and found something I needed. Filter functionality would have made this trivial and it would have made my task much easier.
I don’t claim that there is an easy way to add this functionality as it simply does a directory scan. To do this type of searching you’d have to either search the projects on the fly (ew…) or come up with metadata on each project and store it in a database. This is not impossible task, and I think it would help all uses out a lot. I submitted a feedback report on this <feedback://showreport?report_id=47629>
Xojo Forums: The Xojo Forums are a wealth of information. Years worth of questions and answers make this my go-to resource for general questions. However, the built-in search is just a step above worthless and it’s sometimes easier to use Google instead to find the information that should be a simple search in the forum.
The Xojo Forum is often slow to respond and the Notifications dropdown is, for me at least, an exercise is patience as it’s so slow. It’s obvious that esoTalk does not scale properly with 314,000 posts. Perhaps it’s time to look into something more robust.
Discoverability in Xojo isn’t important for just new developers. It’s a useful and important feature for everyone since the API is too big to know everything. While there are many parts of Xojo that help you in discovering classes, events, properties and methods you didn’t know about they are scattered and disorganized. Searching is an important feature and there are times when searching doesn’t exist or isn’t as helpful as it should.
If you could make Xojo better in terms of discoverability, what would you do?