RhinoCommon API documentation - wishes / critique

Fields are missing in the new Documentation:

https://developer.rhino3d.com/api/rhinocommon/rhino.rhinomath

Here they are in the old:

Example

Great suggestion. I pushed an update to expand the sections by default when you click on the top level class.

1 Like

Thanks Tom, I logged it here.
https://mcneel.myjetbrains.com/youtrack/issue/WWW-2061/Fields-are-missing-from-new-devdocs

I’ll get to it soon

I made some changes that makes overloads act as independent entries. Does that work better for you @Tom_P ?

Dear @mkarimi
thanks for your work. nice to see the progress.

I checked one (fictional) workflow - test scenario.
Let s say I search for
curve offset
or
curve NormalizedLengthParameter(s)

overloads

searchbox: offset
3rd hit ist Curve.Offset which is overloaded…
click on the result

I still get all 3 overloads in one main window
but the title Offset method is missing for the 2nd and 3rd overload…
the tree to the left is not scrolling / showing the correct possition

by clicking on the left tree
Curve → Method → Offset
I only get one Method-Description Overload / definition in the main window.

while the best overview of al Overloads is in the main
Curve → Methods … overview / main window…
( that can only be reached with a lot of scrolling)

I still think that getting an overview on overloaded Definitions should be easier.
the screenshot shows the overview on all “offset” Methods.
I have to scroll twice - the main window and the tree.

that s the corresponding view from the old docs - 2 mouse clicks

scrolling

I like that the left tree is scrolling to the correct branch, even if navigation is not via tree. - that s great.
but scrolling does not work as expected if navigation is coming from the search-results.

kind regards -tom

1 Like

Hi @mkarimi,

this user question is a good example of how confusing the new help doc can be for users which never worked with the old docs:

The AngularDimension in the new docs lists multiple constructors which do not exist, eg. the one with 5 inputs is only there since Rhino 8. I do not see the methods which where located under Create in the old docs:

grafik

I would like to repeat my wish to list all constructors with seperate tree nodes (preferably including their arguments) as it has been in the old docs. The current system requires too much scrolling to find the required constructor or to note that there are multiple constructors available to choose from.

One thing which i find more annoying than useful is that i cannot open multiple sub nodes at the same time eg. Constructors, Properties and Methods. It seems to collapse expanded tree nodes once i expand another sub node:

HelpDocProblem

Could you implement it in a way that when a user CTRL clicks on a node to expand it that it collapses all others and without CTRL is keeps the expanded ones expanded ? This would keep the old functionality and adds the new one on demand.

thanks,
c.

3 Likes

@clement regarding your first two issues: This was a consequence of
WWW-2047 Developer docs: readability of information in tree view, add one extra level of nesting

Right now in the new website, when clicking on e.g.Constructors, the right view gives you all the constructors with their overloads. The left column is simply too narrow to display all info. So the idea is that the left tree simply gives you an overview of the available constructors, methods etc., and the right view gives you the overloads.

In order to make a meaningful YT for this: Why is this a problem?

Hi @Gijs, the problem is that it is no longer possible to keep multiple entries in the tree open at the same time. Eg. when i need to look up information in the DisplayConduit and DisplayMaterial sections simultaneously i preferred to just keep them expanded. This has been possible with the old html help system and is possible using the chm which i still use most of the time.

Instead of replacing this useful functionality with the new way (only one sub node stays open at the same time) it would have been better to let the user decide how this tree behaves. My suggestion would be to keep the old behaviour but still allow the new behaviour eg. by clicking on a tree node while holding the CTRL key. This is btw. a common behaviour with expanding / collapsing eg. in NotePad++. Alternatively the html page could have an options page to control the tree behaviour.

Yes, but imho this involves unnecessary clicks on the tree item and scrolling in the right column. The name space entries in the right column are not what i’m complaining about when talking about constructors. I would prefer to have constructors in the tree as seperate nodes to indicate that there are either multiple or not (this was indicated by the + sign to the left of a node even when that node was collapsed). Using the new help system, i first need to click on the constructors tree node to see the content in the right column.

_
c.

3 Likes

I apologise if this has already been covered above (did a quick search without results), but the mobile experience is also worse with the new docs. At least on iOS Safari on my iPhone 13 mini. And especially in portrait mode where the right side information window all but disappears:


Landscape isn’t much better, but one can at least read it:


The old docs behave like a “normal” website (i.e. one can pinch zoom in and out to view things). Where the new one has these different windows one can just pan around in, sorta :thinking:

1 Like

Tapping this button toggles the navigation tree so you can see the content on the right side.

1 Like

Ahhh, totally missed that, thanks. You still can’t pinch zoom out though it seems, so it feels like panning around a “restricted box”.

That’s just how mobile responsive websites work. Try Wikipedia, the free encyclopedia or any other modern website on your phone for example.

If I may give some suggestions how to improve the CSS on mobile. Before on the left, after on the right.

  • Decrease the left/right padding of .q-item to 0px
  • Actually make the left and right column (.row>col-8) both 50% width. It makes the labels much more readable, while the small text on the right is still fine
  • Increase the gap between the 2 columns
  • Make the label and text appear more like they are on the same baseline ( .q-item__label+.q-item__label { margin-top: 1px;}
  • Please remove the letter-spacing from the text on the right ( .text-caption { letter-spacing: 0;}. There is in 99% of cases no point in increase letter-spacing and it actually makes takes harder to read
  • The text on the right needs word-break: break-word, so that long strings like URLs don’t run off at the right border. I also think that all URLs should actually be clickable for it to make sense :wink:

  • Increase the spacing at the very top between the breadcrumb and title, title and text and text and table
  • Give the toggle title a lot less indentation

I would also try to fix the search field at the top so that only the search icon is visible and when you press it, the search field opens up. Something that you see with most search fields on a mobile header. It’s just a few lines of CSS and Javascript.

I hope this helps. I have worked as a web designer and in recent years as a full-time UX designer for many large companies.

3 Likes

Thank you @seltzdesign , all great suggestions. I filed it here and hopefully will get to it in the near future.

I’m also wondering if there’s any value in open sourcing this site so users like yourself can contribute. What do you think @stevebaer ?

Isn’t it public already?

Right! it is

@seltzdesign if you’re up for it feel free to make a PR and have either me or Steve review and merge it.

1 Like

enum needs some care to (always) show numeric values.

example PointContainment

old

old documentation shows the corresponding numbers

new

new documentation does not

https://developer.rhino3d.com/api/rhinocommon/rhino.geometry.pointcontainment

and the table rows might have less height ?

thanks for the next steps.

kind regards - tom

Enums start at 0 unless specified, but doesn’t hurt to show them anyway.
I filed your request here: https://mcneel.myjetbrains.com/youtrack/issue/WWW-2112/Enum-needs-to-show-numeric-values.

1 Like

And it’s fixed now.

3 Likes