[asterisk-dev] [External] Re: Final Preview: docs.asterisk.org

[Martin McCarthy]

Good morning guys, I hope you're well. I've had a chance to preview the 
new Asterisk Docs page and it's looking good. However, there are a few 
points I would like to note and direct at the developer in order to 
improve the current layout of the site;

Just for reference, I was browsing using the following settings;

- OS: Windows 11 (21H2)
- Browser: Google Chrome 115.0.5790.99
- Screen Resolution: 1360 x 768

==================================================
Desktop Site
==================================================

- The content of the footer is left aligned. This seems "off" to me. 
Usually I see footer content centered. Try centering class 
"md-copyright" and observe how that looks.
- There are dropdown buttons but they do not dropdown and reveal 
submenus as one would expect. Class "md-nav__icon md-icon", you may use 
JavaScript here to reveal the submenu and allow the user to navigate 
quickly through the menus. Currently, two page loads are required which 
slightly hinders the UX and also creates double load on the host web server.
- The main page content does not span the width of the screen. You can 
use the CSS "vw" property to extend the width of the main content div 
"md-content". "vw" or viewport width, will allow the content to span the 
entire screen width regardless of device.
- The main subheaders have links to blank pages. My suggestion would be 
to remove links on those subheaders and revert to my earlier point 
regarding the dropdown menus. There's no point linking to a blank page.
- The footer disappears on pages where the content goes offscreen. It's 
jarring to have the footer pop in and out. On other pages, it appears 
fixed due to lack of content. Consider having the footer fixed in place 
just like the titlebar.
- Table of contents. Consider adding an arrow or some symbol to the TOC 
active element to allow users to visually inspect their current 
position. md-nav__link--active CSS can be modified for this.
- The TOC has a scrollbar on it which seems out of place. Consider 
applying an overflow CSS attribute to md-sidebar__scrollwrap to hide it.
- There seems little point to me in indenting items in the TOC. Consider 
removing indentation and reviewing how it looks and how using it without 
feels.
- The search bar width is small then when clicked expands. This is 
jarring to use as an end user. I recommend a consistent width for the 
search box that does not expand. This will allow for a consistent UX.
- The project logo is present but not the name of the page. It's prudent 
to add the name of the project next to the project logo to inform users, 
those who don't have images or simply don't recognise the logo, that 
this is the Asterisk Docs page.
- Back to top only appears if a user scrolls up. Have that functionality 
available whenever a user scrolls past a certain point (for example 
100px or more from the top of the page.
- Subheaders and subheader menu font is exactly the same and as such, 
these all blend into one when looking at them. Consider changing the 
style of the subheaders and / or the submenu items to allow for easier 
dinstinction betweeen them. Maybe consider smaller fonts or horizontal rule.
- Consider a scroll animation when clicking an element of the TOC. That 
would make the UX a little more fluid. It doesn't have to be fancy, a 
simply scroll to effect to the selected link would suffice.
- Consider using a different style for the content headers as they blend 
into the main text.
- There appears to be an animation on md-source__repository 
md-source__repository--active but it really is so subtle, if you 
literally blink, you'll miss it! Maybe reconsider that one. If you want 
to animate it, consider what you want to do with it. Do you want to 
highlight the project's stats? If so, consider something like a countup 
animation to highlight the stats.
- Consider the colour of both header and footer to fall into a cohesive 
colour scheme.
- Consider the height of both header and footer and if possible, and it 
looks possible, to have them both the same size.
- There appears to be 50px+ of overlaying whitespace when the footer 
appears. This obscures part of the navigation submenu. Not only that, 
the navigation submenu scrolls beneath the footer. Have the navigation 
menu not scroll under the page have it fixed inside it's designated 
space on the page.
- Some pages have ToCs, some don't. Try to maintain consistency.
- Consider the placement of the header items. Something like this would 
fit logically for me personally -> "Company Logo" --- Github Project 
Details --- Search Bar --- App Settings (Dark Mode).
- When applying dark mode, consider the header icons as they still 
illuminate brightly.
- Consider the sizing of the footer icons. They are very small and maybe 
could be a touch larger for accessibility.
- A link to the IRC channel would be nice :) Use the Hashtag SVG icon if 
you wish.

==================================================
Mobile Site
==================================================

Phone used: Samsung Galaxy M32
Browser: Google Chrome 115.0.5790.166

- Right off the bar, when I load the page, I have no idea I'm in the 
right place. No logo or page title. 3 stacked lines, the dark mode 
button and search icon. Consider placing some branding there on the 
header itself.
- Ensure the spacing is appropriate. The 3 icons are not aligned in a 
consistent manner. If you only have 3 icons, it might make sense to left 
align, center and right align them.
- Docs on mobile defaults to "dark mode" is this intended behaviour?
- On the submenu, consider the placement of the project logo and title.
- Don't allow for submenu items that navigate to nothing to be 
clickable. Navigate down the tree until there is content to show.
- The Back To Top button behaviour is inconsistent. When scrolling up, 
it appears but may disappear depending on the content. Have it fixed.
- When going back one page, don't have the menu expanded. Instead, 
scroll to the last content page.
- Don't allow scrolling of the content when the submenu is open.
- Consider keeping the logo and title on the submenu fixed in place for 
consistent design.
- Noticeable clipping on the submenu when reaching the footer of the the 
page.
- Consider the footer alignment of elements and sizing of the project links.

I'm happy to assist with the code and design if needed. You can reach me 
on here or you can reach me on Libera.Chat in #asterisk. Thanks guys.

Martin.

On 09/08/2023 23:43, George Joseph wrote:
> On Wed, Aug 9, 2023 at 4:05 PM George Joseph <gjoseph at sangoma.com> wrote:
>
>     On Wed, Aug 9, 2023 at 2:30 PM <asterisk at phreaknet.org> wrote:
>
>         On 8/9/2023 11:12 AM, George Joseph wrote:
>
>
>         > Yeah, create an issue.  I can take a look in the coming
>         weeks.  If you
>         > constrict the width of your browser, at some point, the left
>         nav bar
>         > will collapse and you can get it back by clicking on the
>         "hamburger"
>         > button that then appears in the top-left of the page. 
>         There's no way
>         > to collapse it manually though so maybe we can find a way to
>         add that.
>         > Maybe we can also make the page table of contents
>         collapsible.  Both
>         > should give more space to the content.  I think we can also
>         override
>         > the viewport width of the content.    A tweak to the dynamic
>         > documentation generator might also help.
>
>         I don't think the issue here is collapsing the navigation. In
>         fact, I
>         really hate when you're on a large monitor and websites
>         collapse menus
>         like that, catering to mobile devices only is pure insanity,
>         making life
>         more difficult for everyone else by requiring yet more clicks
>         to do
>         anything. The issue is that the site seems to max out at a
>         certain
>         viewport; on a large monitor, the middle portion could take up
>         more
>         room, but there is vast whitespace to the left and right
>         margins. It's
>         possible that the style is assuming a max-width that it will
>         use for
>         presentation. Ideally, the middle content should expand to
>         take up the
>         space it can so it can use the full width of any monitor.
>
>
>
>     Yeah I get it.  I was just throwing out some additional ideas as well.
>
>
> Simple change.  Check now.  You may have to clear your cache or at 
> least look at a page that's not currently in your cache.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230810/368317c5/attachment-0001.html>