Remarks about the preview version of the Blazorise documentation

[iwis]

I have a few remarks about the new version of the documentation (https://preview.blazorise.com/docs) :

1. Horizontal menu:
   • Make it smaller or not sticky
     Reasons: 1. more text will fit on a web page; 2. current documentation doesn't have sticky menu; Vuetify and Bootstrap docs have a sticky menu but it is smaller.
2. Vertical menu:
   • Fit more items on a computer screen
     Reasons: 1. component searching will be easier; 2. there are more menu items on a screen in Bootstrap, Vuetify, and the current Blazorise documentation.
3. Sample code (a div with the blazorise-codeblock CSS class):
   • Reduce the font size and/or the line height
     Reasons: 1. more text will fit on a web page; 2. Bootstrap and Vuetify docs use smaller fonts.
   • The code should be able to occupy the entire black window, currently it cannot reach its right edge
     Reasons: 1. it doesn't look elegant now; 2. more text will fit on a web page; 3. Bootstrap and Vuetify docs don't have this problem.
   • Reduce the bottom padding of the black window (technically it is the bottom margin of the <pre> tag, equal to 1 rem)
     Reasons: 1. the bottom padding is larger than the top padding, which doesn't look good; 2. more text will fit on a web page;
     3. Boostrap, Vuetify and the current Blazorise docs don't have this problem.
   • (probably controversial) Put opening brackets in the same line (https://en.wikipedia.org/wiki/Indentation_style#Variant:_Stroustrup)
     Reasons: 1. more text will fit on a web page; 2. opening brackets are in the same line in JavaScript code in Vuetify and Bootstrap docs
   • I like a light background more - like in Vuetify or Boostrap docs, although it may be a matter of taste.
4. Table describing attributes
   • I don't like that the first three columns of a table have the same red font. In Vuetify documentation, fonts of these columns are different - the name column stands out because it is the most important.

Of course some or most of remarks can be a matter of taste!

[stsrki]

Thank you for the feedback. You have valid points for the most part. We already did some improvements in the docs, but we need to upload it. And we will definitely implement some of your suggestions.

Thank you for taking the time to write it down. I really appreciate it.

[stsrki]

@iwis we have made changes to the documentation and published a new version https://preview.blazorise.com/

The only thing we didn't do are:

• brackets on the same line - don't like this style
• light background for code - will consider it for the future versions

[iwis]

brackets on the same line - don't like this style

No problem, it isn't relevant anymore after reducing the font size.

light background for code - will consider it for the future versions

Maybe also change the background of the vertical menu. I like the light backgrounds in Bootstrap, Vuetify and other documentations more. But it may be a matter of taste.

Below are other remarks:

Mobile version

(Tested in Google Chrome mobile on an oldish Samsung Galaxy S7 with the 360x640 viewport resolution, but newer Galaxy 8/10/20 have the same width i.e. 360)

• (very important in my opinion) I think that vertical menu shouldn't be displayed on smartphones permanently
  Reasons: 1. The constantly visible menu (even collapsed) greatly limits the available width on a smartphone screen; 2. The remaining content visible on a web page is squeezed; 3. Boostrap, Vuetify, https://material-ui.com/, https://material.angular.io/ documentations and the current documentation of Blazorise don't use such menu.
  I think it's better to use a menu similarly to other documentations. I think that it should be changed also in the demo website (https://bootstrapdemo.blazorise.com/).

  

• A blank space appears at the bottom of the page on a horizontally rotated screen.
  It is also visible in the Google Chrome browser on Windows 10 if the window size is changed to 360x640 pixels. So it is probably
  reproducible on other smartphones.

  

General

1. Vertical menu

   • Expand the current category after opening a web page
     Steps to reproduce: 1. Go to https://preview.blazorise.com/docs/components/date. 2. The "Form" item isn't expanded.
     Reasons: 1. I don't know where the current page is in the menu. 2. All documentations checked by me (Boostrap,
     Vuetify, https://material-ui.com/, https://material.angular.io/) expand the current category.

   • Don't forget which categories are expanded after changing the width of a browser window
     Steps to reproduce: 1. Select an item from the vertical menu, e.g. "Form > Date"; 2. Decrease the browser window width below 992px. The menu collapses; 3. Increase the browser window width above 992px. The menu expands; 4. The "Form" item hasn't been expanded.
     Reasons: 1. It is quite annoying; 2. There is no reason why the menu state should be forgotten. 3. It works in all documentations checked by me (Boostrap, Vuetify, https://material-ui.com/, https://material.angular.io/)

   • The indentation of "Getting started", "Binding Data", ... positions in "Extensions > Datagrid" seems too large to me.
     https://preview.blazorise.com/docs/extensions/datagrid/getting-started

2. Sample code (a div with the blazorise-codeblock CSS class):

   • I don't like the horizontal scrollbar in the middle of the black window between HTML and C# code on the https://preview.blazorise.com/docs/components/accordion page and on many other pages, e.g. Components > Alert, Card, Grid etc.
     This can be solved by limiting the line length to 136 characters (The text "Anim pariatur cliche ..." can be put on two lines)
     or by displaying a scroll bar at the bottom of the black window.

[stsrki]

I made many improvements in the meantime and the new version is uploaded.

Some of your suggestions would need to be implemented or fixed in Blazorise to make it possible. Specifcally:

• Auto expand of Bar items on navigation
• Indentation of sub-items

Other fixes are also on the way. Definitely looking better already :)

[iwis]

Yes, it looks pretty good now. Changing the background of the vertical menu brought a lot of freshness. In my opinion, there was too much black background on the page, I thought it could be the background of the examples, but it was mainly the background of the vertical menu.

I made a list of documentations of the most popular component libraries in JavaScript:

Material Design:
https://material-ui.com/components/buttons/ (70k, React)
https://vuetifyjs.com/en/components/buttons/ (32k, Vue)
https://material.angular.io/components/button/overview (22k, Angular)

Other:
https://ant.design/components/button/ (74k, React)
https://quasar.dev/vue-components/button (20k, Vue)

Boostrap:
https://getbootstrap.com/docs/5.1/components/buttons/
https://react-bootstrap.github.io/components/buttons/ (20k, React)
https://dev.bootstrap-vue.org/docs/components/button (13k, Vue)
https://ng-bootstrap.github.io/#/components/buttons/examples (8k, Angular)

Indeed, no library uses dark background for the vertical menu. Two libraries use dark background for the examples, and it looks pretty good.

Tomorrow I will write a few more remarks, with references to other documentations.

[iwis]

I compared the look of Blazorise documentation with other documentations. You can also (see the picture):

1. Unify the menu height to 64px or 50px. I don't know if 64px or 50px is better - most libraries use 64px, some use 56px or 50px. Sticky 72px menu was too big together with the big font of code examples.
2. Maybe improve the color scheme of the web site for example:
   a. make the background of a selected item in the vertical menu more pale?
   b. decrease contrast of the vertical menu slider
   c. decrease contrast of the page slider

Generally, maybe the look/colors could be improved a little, but I am not good at this, so I don't know.

[stsrki]

I like when the last few issues are just small tweaks :)

Thank you for all the comments so far! It really helped us to focus on important parts and the end result is really good.

[stsrki]

New version is up if anyone wishes to test :)

[sturlath]

One thing I find annoying (sorry ;-)) with the docs is that if I have scrolled down on one page and click some other, the new page opens in the same scroll position as the the previous one.

[stsrki]

Oh yeah, I forgot about that. I will try to fix it. Thank you!

[stsrki]

New version is up :)

[iwis]

5 remarks are not fixed:

• Bar: Vertical menu - Expand the current category after opening a web page #2888
• Bar: Vertical menu - Don't forget which categories are expanded after changing the width of a browser window #2889
• Documentation: Vertical menu - The indentation of subitems seems too large #2890
• Documentation: Scrollbar in the middle of a sample code #2891
• Documentation: Mobile - A blank space at the bottom of the page #2892

Should I create new GitHub issues (or only one issue with checkboxes as above) to not forget about them?

All other my remarks about documentation were fixed.

[stsrki]

I would create a new ticket for most of the mentioned issues. They require more fixes and improvements on the Bar component itself that is not part of the docs PR.

Sample code (a div with the blazorise-codeblock CSS class): I don't like the horizontal scrollbar in the middle of the black window between HTML and C# code on the https://preview.blazorise.com/docs/components/accordion

The reason for the two scrollbars is that they are separated by cshtml and csharp blocks of code. And they both have separate color schemes.

[iwis]

I have copied text of remarks to new GitHub issues.

The reason for the two scrollbars is that they are separated by cshtml and csharp blocks of code. And they both have separate color schemes.

You can make a single scrollbar using the overflow CSS property - see #2891. I checked that it works.

[stsrki]

I have released a new version for bug fixes for the, and also with the new News section. At the moment only with two pages.