New Documentation feedback

[anon20074439]

I’ve just read the post about the new documentation system so I thought I’d take a look and post some initial feedback on it.

• Search

I’m unable to jump right to where I want to go, as an example, if I search for FolderItem and hit enter it takes me into ShowSelectFolderDialog inside FolderItem, not to the root because as I type it’s limiting my results, but why to something 3/4 the way down the page, what made that the top hit in FolderItem?

If I search for Close I’d want to see a list of where Close is used and not end up where it thinks I should be, in Close for the deprecated ListBox.

• Mobile View

If you search in mobile (shrink the width of the window to simulate that) and click and entry on the nav you’re taken to just after the entry, so the heading of where you’re meant to be is obscured, just off the top of the screen.

• URL

The url is horrible, can you put it on documentation.xojo.com ? I see that you use a redirector when opening up the online docs from inside the ide so wouldn’t it be “easy” to redirect all older editions to a different url (legacydocumentation.xojo.com?) tweak the target url parameter in 2022r1 to docs instead of documentation so you can check for that and redirect those to documentation.xojo.com while sending all the older ide’s to the legacy docs?

• Layout

There are no clear defining demarcations between sections so everything seems to flow into one homogenous pile of text. This can be seen in FolderItem where Enumerations just seems to fall into Property Descriptions. This could be work a little better if, for example, each property were listed in the nav, like you do with enumerations. At a glance, you could then see where you were. If I’m in the middle of looking through a list of properties on for example, FolderItem, there’s no way to see what other properties there are without scrolling back to the top to look at the list again as the entries aren’t shown in the nav broken down in their sections. MSDN does this slightly differently with a right nav for the location content that moves as you scroll the page so you can easily see here you are.

The font choice of the signatures is very hard to tell apart from the description, it doesn’t POP out at you that this is the thing you need to be taking note of, maybe you could change this to the code font this will also demark the blocks of text a little better. For example, with FolderItem.DriveCount, the same font is used for the DriveCount in the signature DriveCount As Integer as the entry a few lines down in the description and the “This property is shared.” looks almost identical in that its a small bit of text ending in a link, the only difference being the ever so slight bolding.

• Navigation

The navigation on the left doesn’t highlight the section I’m currently viewing on the right side as is seen in some other documentation systems so I don’t quickly know if I’m looking in the properties of something or the events if I have, for example, come here via search or a link. There’s also no drilling down into the list of properties for example.

• Linking

There is no way to link directly to sub items without copying the link from the very top of the page where the hastag is inserted to jump you to the correct section. I see there’s a link when you hover over section headers, but not things like property names, event names etc which will make it more cumbersome to link to the forum to help people.

• Copy

Could there be a Copy button on the code blocks, maybe in the top right corner?

• Code colours

Is there a particular reason that you didn’t stick with the code colouring from the IDE or will the IDE’s default colours be changing to match the docs? Also, Var isn’t highlighting correctly, its white (in dark mode), the same as the variable name and also Classes are wrong so the code looks ever so slightly odd and isn’t as easy to read as when it’s in the IDE.

• Input

When you open the site, either from the ide or browsing, could you put the caret in the search field so its ready to receive input, can you imagine google not doing this when you visit google.com

Overall its a lot cleaner and on a quick viewing, it looks like a good platform to build on and move forward.

[Beatrix_Willius]

Searching for listbox:

Where is the desktop listbox in the results?

Why does the scrollbar turn red when scrolling?

[Beatrix_Willius]

The search is super weird. There is no scrollbar in the results. It only searches for words and not for partial words.

Starting a search for “acceptfiledrop”:

As listbox doesn’t work I’ve tried to search for all the desktop controls:

[Geoff_Perlman]

There’s still work to be done to get the search results just right. Some of it involves tweaking the underlying engine and some of it is content changes. For example, we don’t want to have the class name in any of the headers on the page (except the top of course) or it will think those are important.

[Sascha_S]

Overall i like the new design. I hoped for something more like a wiki, but it’s usable.
What i do not like is the waste of space. Esp. on smaller screens:

[Jeremie_L]

@anon20074439

• Copy

Could there be a Copy button on the code blocks, maybe in the top right corner?

This is an excellent idea!

[Geoff_Perlman]

Thank you for the detailed feedback. This is the first test build of course so there’s much more work to do.

@anon20074439

I’m unable to jump right to where I want to go, as an example, if I search for FolderItem and hit enter it takes me into ShowSelectFolderDialog inside FolderItem, not to the root because as I type it’s limiting my results, but why to something 3/4 the way down the page, what made that the top hit in FolderItem?

We are still working on the search behavior. By the time we release you will be able to type in a class and go directly to it as well as class.member to go straight to the member. As for the results, there’s more tweaking we need to do.

@anon20074439

If you search in mobile (shrink the width of the window to simulate that) and click and entry on the nav you’re taken to just after the entry, so the heading of where you’re meant to be is obscured, just off the top of the screen.

Yes, more CSS tweaking there.

@anon20074439

The url is horrible, can you put it on documentation.xojo.com ?

Eventually it will be but remember that most people don’t ever type the URL.They use the docs from within Xojo. But if you do use it from a browser, your browser will quickly learn to autofill it for you. Having said that, eventually documentation.xojo.com will point to the new docs.

@anon20074439

There are no clear defining demarcations between sections so everything seems to flow into one homogenous pile of text.

This is a top-down design. At the top of the page you can see the basic information about properties, methods, events, etc. If you need more details, the names are links which will take you to the description. There are labels in a larger, bolder font that indicate Enumerations, property and method descriptions.

@anon20074439

There is no way to link directly to sub items without copying the link from the very top of the page where the hastag is inserted to jump you to the correct section.

It may not be obvious but if you scroll down to a particular property or method description, the URL does change so you can copy it to get a URL for that specific property or method description.

@anon20074439

Is there a particular reason that you didn’t stick with the code colouring from the IDE or will the IDE’s default colours be changing to match the docs?

That part has not been fully configured yet and doesn’t even have our keywords list (hence Var doesn’t highlight). Could you elaborate on the “classes are wrong” ?

@anon20074439

When you open the site, either from the ide or browsing, could you put the caret in the search field so its ready to receive input, can you imagine google not doing this when you visit google.com

That IS what it does in the IDE. I’ll see about getting it to do that in the browser.

@anon20074439

Overall its a lot cleaner and on a quick viewing, it looks like a good platform to build on and move forward.

Agreed. This is the very first test build. There’s still a lot of work to do. There are errors in the documentation from the conversion process and we will be cleaning those up during the test cycle.

[Geoff_Perlman]

@Sascha_S

What i do not like is the waste of space.

Because the list is hierarchical, there needs to be some room to expand it.

[DerkJ]

@Geoff_Perlman

Eventually it will be but remember that most people don’t ever type the URL.They use the docs from within Xojo. But if you do use it from a browser, your browser will quickly learn to autofill it for you. Having said that, eventually documentation.xojo.com will point to the new docs.

Where did you get that from? Our team, including myself mostly use the browser url, not the internal (local) docs. Including that documentation.xojo.com is the go to (known) url. Having yet again another url (we had that before) is not gonna make it more clear. Please just re-use documentation.xojo.com if possible !

[Geoff_Perlman]

@DerkJ

Where did you get that from? Our team, including myself mostly use the browser url, not the internal (local) docs. Including that documentation.xojo.com is the go to (known) url. Having yet again another url (we had that before) is not gonna make it more clear. Please just re-use documentation.xojo.com if possible !

In the past it was sometimes necessary to use a browser because the IDE contained only the language reference. Now the Documentation window in the IDE is identical to that of the browser. Also, the difference between the two URLs is a single character. I type “doc” to get to the old docs and “docu” to get to the new ones. We need to keep the old documentation at documentation.xojo.com because there are a LOT of URLs out there that point to it. Eventually we will redirect to the new documentation but don’t want to do that immediately.

[Ian_Kennedy]

But it does feel overly large. There is quite a gutter margin on the left which likely could be reduced. Likely also on the right. I really don’t like the “nasty green scrollbar” either. I find it off putting. I know it’s the colour of xojo… but.

[Ian_Kennedy]

I’m still getting used to the “Everything on one page” approach. It seems like an awful lot of scrolling to get to where you need to be. I’m missing the overview at the top of the page that fitted on one screen that we had before. Now listbox’s properties / methods etc takes about five scrolls to get to the bottom of them. I may get better with time.

[Geoff_Perlman]

It takes more scrolling on larger classes but there’s also a lot more information in those top tables compared to the old docs. You can also do a search (via the browser - perhaps we can add it to the Documentation window) across the entire class because it’s all on one page.

[Ian_Kennedy]

Search only works if you know what you are looking for. If you are trying get to know the class it is not an option. Still just a first impression.

[Geoff_Perlman]

True but if you’re trying to get to the know the class, I think the new organization is far better. You can see an overview of the class at the top and can click the links to scroll down for details or just start at the top and scroll through the page reading about each class member. That was difficult with the old docs. You’d be clicking back and forth constantly.

FWIW, in Safari if you have clicked a link at the top of a class page to get to the description of a property or method, swiping right (both on macOS and iOS) will reveal the same page but scrolled back to the top.

[Ian_Kennedy]

Sure Command Left arrow does the same.

[Lars_Lehmann]

My list:

• I don’t like, that the new documentation forces you to use the dark/light mode depending your OS settings.
• The specific sections are floating into each other, it’s pretty hard to determine where one section starts and another ends. (see img 1) This could be a better approach:
  → Devide main sections with a line (Properties, Methods, Enums etc)
  → The font size of the headlines could be more apart in size
  → The headline should have another font as the content.
• The declaration line of properties for instance are hard to tell apart from the content (see img 2)
• The search is horrible.
• The menu doesn’t highlight your current position
• There’s no way to copy the link of a search. Sometimes you just want to share the list of search resaults rather than a single object.
• There’s more, but this were just the things wich annoyed me directly

Img 1 → where ends a section? where does the next start?

Img 2 “Count as Integer” is not elevated enough to be easily “scanned” by the human eye

[DerkJ]

@Geoff_Perlman

Now the Documentation window in the IDE is identical to that of the browser

Please use this viewer on windows and you’ll see it’s not close to a browser. It seems to be leaking memory and processes when it had been opened. This is why we use a webbrowser more than the local (in-ide) docs browser.

I do see why the urls should stay as it’s linked from all over the web.

[Ian_Kennedy]

@Lars_Lehmann

I don’t like, that the new documentation forces you to use the dark/light mode depending your OS settings.

I would have thought that was the correct thing to do. The user has specified the choice, why would you want to ignore it. Especially when that user is you.

[brian_franco]

I agree, I mean they are your settings so why would/should the documentation ignore this?