@mkarimi, i’ve tried to use the new html help system during the past week and found that there is still a lot which makes it very hard to find the required information. Please see below images where i used the Brep.CreatePatch method for comparison.
The old sandcastle generated html help page:
The new help looks like this:
Let’s start from the top: The tab titles in the browser of the old help system displayed the method name “Brep.CreatePatch Method (…)” while the new system always displays the link with the https:// stripped: developer.rhino3d.com/api/Rhino…
When i have multiple tabs open in the browser, it is almost impossible to to find what i have already opened.
In the new help system, imho the tree column on the left shows 90% unneccessary information because the method arguments are displayed behind the method names. Since this is all displayed in the same font and without line breaks, i think nobody will ever make the column wide enough to display what is shown. I mean this:
was displayed in a very compact way in the old help system while it did not show any other method once the method page was entered:
The CreatePatch method is available in 3 different ‘flavours’, having different method overloads. The old system does have one extra parent entry for CreatePatch in the namespace tree, but the new system instead shows 3 times the same entry in the tree. Regardless on which entry you click, you get the same page in the right column listing all 3 methods below each other which requires to scroll and find the method you’re searching for. This means, 2/3 of information in the right column is shown which the user is not interested in. This does make the tree much longer having all these extra items. A single parent item (with subitems) would be preferred instead.
The tree view in the old system was imho easier to read and find information in as it did omit method arguments for most of the entries. It did show this information only when the parent item of CreatePatch was expanded and when a parent item existed. The new tree is imho harder to use visually because the intendation of the first tree level is more narrow then all following levels. (it saves a bit of screen space though).
A better text intendation in the right column could possibly help to make the content more readable along with better differentiable font styling. The old system was using 2 intendation levels with constant size below the larger text headlines:
The new system, also uses 2 intendation levels but the width for the first level is not constant. I think the Parameters and Returns headlines should start at the same intendation level as the Description headline:
What makes the right column of the new help system less readable is imho:
- too small font for the Description, Parameters, Returns headlines
- the Syntax headline is missing and the content uses random line breaks for the parameter names
- eg. the Parameter headline should use a larger font as the parameter names
- ideally, the parameter names might be non bold but italic as the in the old system
The parameter name description is less usable in the new system. It is missing the type description in many cases. I mean this:
was shown like below in the old system and helped the user to understand how the Type Enumerable of geometryBase must be passed to the method:
It also was possible to click on this link and get right into the microsoft docs in the old system. The new system just displays the type name in a link color, but if you hover over the link, you’ll find out it’s actually not a link and the mouse cursor changes to a “no parking here” symbol. 
The syntax rectangle in the old section had a “copy” feature in the upper right which was quite useful to get the argument (parameter) names without retyping them. The new system does not have this yet.
The Returns section in the new system does not display the Type of the returned value. Using the CreatePatch method for example it reads:
A brep fit through input on success, or None on error.
This might be confusing for users of the C# language, i guess there is no None (only in Python), shouldn’t this be Null instead ?
I don’t want to complain too much here but have to conclude, the old sandcastle system was making a clever use of html font styling, line heights, intendation and colors. Probably i’ve got used to it too much which makes it hard to adopt.
The dark mode in the new system is highly welcome but it requires slight color tune ups especially for the parameter types (the non links). The bread crump links on top of the new system’s right column are useful, something which the old system did not have.
_
c.
