No, the new documentation is waaaaaayyyyy worse than the old docs.
I don’t remember what I was searching for in the morning. I selected the first search result in the new docs. It wasn’t what I was looking for. In the old docs I could either select the next result in the right sidebar (local) or go back to the search result (website). In the new docs I have to search again.
Edit: the pages in the new docs are too long. In the old docs I had a quick overview. In the new docs I have to scroll like mad.
I 100% agree with this statement. The new docs read like a run-on sentence. The old docs were better at helping you drill down to what you were looking for in consumable bites. Not that the old docs were perfect, but they were way more helpful than having to scroll through a long page of information that isn’t necessarily logical in it’s organization.
I still think the old docs loaded into Dash is the best I’ve seen among the ways to navigate Xojo docs. Here’s a screenshot of the example you just gave, but using Dash:
Here is another. ListBox is a control in the IDE, so user searches for ListBox. In the help and they get this:
ListBox shows up as deprecated, which it is but… Clicking on that leads to a list of deprecated items, you click on listbox in that list and shows the replacement.
The top entry with the “#” is the correct link, but not sure if the user will pick up on that. If you click on that you get the replacements and recommended items for ListBox, which is titled “ListBox”.
Why not just put the proper listbox recommended uses in the top entries; DesktopListBox, WebListBox, etc. I think this is very confusing, especially for a new user.
Here’s the first result for ListBox in Dash. I also like that I can simultaneously search the MBS documentation. Pretty sure I’m beating a dead horse though.
This is the worst search feature ever. Basically is telling you:
“there is a page titled Graphics (little blue text over the enter), Press enter to go there”
Everyone is just expecting to see the name of the result, something like “User interface → Controls → Button” or whatever instead of just an Enter icon
Oh, yes, that was lost on me. I thought it was just showing what I was typing, not the results.
Playing with this more… typing “grap” as in graphics gets you this:
clicking enter gets you to a deprecated item Graphics.DrawPolygon. I wonder why Graphics isn’t shown first versus a deprecated item. Why .DrawPolygon, instead of all the other methods, for example .DrawRect, etc.?
I have a feeling renaming all of those things in the new framework and how this is being displayed in help is going to wreak havoc with new users. It’s very confusing.
My assessment of this thread is that we’re dealing with a generic search algorithm that doesn’t really present results in ways that prioritize what users are likely searching for. Some of this can probably be fixed via how the docs are organized to begin with.
My experience with Microsoft docs (.NET anyway) has been that when it comes to language features (which includes framework classes and their properties and methods), one searches for something in Google, say, String.AsSpan, and you land in the page of the docs devoted to that particular method and can find your away around with the side menu (which is organized by class and property) from there. This IMO is better than a monolithic post about the String class; if you search for that you land on the overview and you have a menu to navigate into properties and methods (as well as a list of those items with links right in the summary page). Each of those is then treated pretty thoroughly, including code examples.
In other words these docs need both more and less detail. More detail overall, but broken down into digestible bits with a page per subtopic. And written with the question in the back of the author’s mind, as a developer what questions am I likely to have? What should I be warned about? How does this relate to alternative ways of doing the same thing and when / why is each of those ways preferred?
I think given the audience (mix of pro and “citizen” devs) more thought has to be given also to directing amateurs to key methods / event handlers / properties and some topics will need to be broken down into something like “advanced considerations” sidebars that can in general be safely ignored by a noob knocking out some departmental app. Some things like the Memory class or scructs will be inherently advanced topics and can be headlined as such. I’m kind of spitballing here but it seems to me like the closer one can get to achieving something like the above, the better.
Put another way – from my admittedly limited explorations so far, each page of the docs tends to carry too much info and that is part of why searching for some particular thing means one has to “scroll like mad”. I tend to think of documentation pages a bit like the advice that’s generally given for method bodies. If it doesn’t fit on one screen it is “probably” in the general case too big and needs to be broken down into sub-method calls. Same goes for documentation, giant topics / walls o’text are generally not a good thing. Each method, property, event should generally have their own page. The class they belong to should have its own summary description page.
I confused about this because the new docs start off the tables for properties, methods and events just like the old ones did with the exception that they actually provide the signatures and other information so you don’t have to click on the items first to find this info. What is happening that you are having to scroll?
I wish the documentation examples were self-contained, or a ‘setup’ – what’s required – is provided to make it run. I don’t recall resolving a problem from reading the doc. Fortunately, the forum has many members ready to help.
The new docs also list the tables at the top but with additional info such as signatures and types so you don’t have to click to go to another page with this info. With that in mind, what about the new pages are less intuitive?
