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

[asterisk]

On 8/9/2023 6:43 PM, George Joseph wrote:
On Wed, Aug 9, 2023 at 4:05 PM George Joseph > wrote:


On Wed, Aug 9, 2023 at 2:30 PM mailto:aster...@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.


It's much better now. Takes up the full screen on a large monitor, on 
several different types of pages. Thanks, George!


--
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
  http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[George Joseph]

On Wed, Aug 9, 2023 at 10:41 PM Martin McCarthy <
martin.c.mccar...@outlook.com> wrote:

> 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;
>
> --snip--

>
> 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.
>
Hi Martin,

While we really appreciate the effort it took to do the review, the goal
of the documentation re-hosting was to get it off of the ancient Atlassian
Confluence infrastructure into a low maintenance environment that can
provide basic usability for the majority of our users.  We believe we've
reached that goal.   Sure, there are things that could be tweaked but given
the size of our team it's difficult for us to justify the resources that
would be required for many of them.   Your offer of assistance is also much
appreciated as would any issues and pull requests you might submit but
please keep in mind that the more customizations made to mkdocs and the
Material theme the more resources it takes to maintain them, especially
when we need to upgrade those tools.

Going forward if there are issues please file them as Github issues[1] so
they are properly tracked.

Thanks!
george

[1] https://github.com/asterisk/documentation/issues
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[Floimair Florian]

Looks a lot better already. Thanks George!

FLORIAN FLOIMAIR
Development
Symphony Cloud Services
Commend International GmbH
Saalachstrasse 51
5020 Salzburg, Austria
Phone: +43 662 85 62 25
Mail: f.floim...@commend.com<mailto:f.floim...@commend.com>
[signature_1051841226]
commend.com
LG Salzburg / FN 178618z


Von: asterisk-dev  im Auftrag von George 
Joseph 
Datum: Donnerstag, 10. August 2023 um 00:43
An: Asterisk Developers Mailing List 
Betreff: Re: [asterisk-dev] [External] Re: Final Preview: docs.asterisk.org

CAUTION: This email originated from outside of the organization. Do not click 
links or open attachments unless you recognize the sender and know the content 
is safe.
On Wed, Aug 9, 2023 at 4:05 PM George Joseph 
mailto:gjos...@sangoma.com>> wrote:
On Wed, Aug 9, 2023 at 2:30 PM 
mailto:aster...@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.


-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

Re: [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.


==
Mob

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

[George Joseph]

On Wed, Aug 9, 2023 at 4:05 PM George Joseph  wrote:

> On Wed, Aug 9, 2023 at 2:30 PM  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.
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[George Joseph]

On Wed, Aug 9, 2023 at 2:30 PM  wrote:

> On 8/9/2023 11:12 AM, George Joseph wrote:
> >
> >
> > On Wed, Aug 9, 2023 at 8:39 AM Joshua C. Colp  > > wrote:
> >
> > On Wed, Aug 9, 2023 at 11:37 AM Floimair Florian
> > mailto:f.floim...@commend.com>> wrote:
> >
> > Thanks Josh!
> >
> > I went the same path actually but gave up, as CSS to me is
> > something completely out of my knowledge domain.
> >
> > I also had a look at the other teams but so far Material for
> > mkdocs does still look like the best option out there readily
> > available.
> >
> >
> > Then I'd suggest filing an issue on the Github repo with your
> > comments so they don't get lost. No guarantee anything can be
> > done, but the docs repo is where issues should go.
> >
> >
> > 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.
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[asterisk]

On 8/9/2023 11:12 AM, George Joseph wrote:



On Wed, Aug 9, 2023 at 8:39 AM Joshua C. Colp > wrote:


On Wed, Aug 9, 2023 at 11:37 AM Floimair Florian
mailto:f.floim...@commend.com>> wrote:

Thanks Josh!

I went the same path actually but gave up, as CSS to me is
something completely out of my knowledge domain.

I also had a look at the other teams but so far Material for
mkdocs does still look like the best option out there readily
available.


Then I'd suggest filing an issue on the Github repo with your
comments so they don't get lost. No guarantee anything can be
done, but the docs repo is where issues should go.


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.


--
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
  http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[George Joseph]

On Wed, Aug 9, 2023 at 8:39 AM Joshua C. Colp  wrote:

> On Wed, Aug 9, 2023 at 11:37 AM Floimair Florian 
> wrote:
>
>> Thanks Josh!
>>
>>
>>
>> I went the same path actually but gave up, as CSS to me is something
>> completely out of my knowledge domain.
>>
>> I also had a look at the other teams but so far Material for mkdocs does
>> still look like the best option out there readily available.
>>
>
> Then I'd suggest filing an issue on the Github repo with your comments so
> they don't get lost. No guarantee anything can be done, but the docs repo
> is where issues should go.
>

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.




>
> --
> Joshua C. Colp
> Asterisk Project Lead
> Sangoma Technologies
> Check us out at www.sangoma.com and www.asterisk.org
> --
> _
> -- Bandwidth and Colocation Provided by http://www.api-digital.com --
>
> asterisk-dev mailing list
> To UNSUBSCRIBE or update options visit:
>http://lists.digium.com/mailman/listinfo/asterisk-dev
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[Joshua C. Colp]

On Wed, Aug 9, 2023 at 11:37 AM Floimair Florian 
wrote:

> Thanks Josh!
>
>
>
> I went the same path actually but gave up, as CSS to me is something
> completely out of my knowledge domain.
>
> I also had a look at the other teams but so far Material for mkdocs does
> still look like the best option out there readily available.
>

Then I'd suggest filing an issue on the Github repo with your comments so
they don't get lost. No guarantee anything can be done, but the docs repo
is where issues should go.

-- 
Joshua C. Colp
Asterisk Project Lead
Sangoma Technologies
Check us out at www.sangoma.com and www.asterisk.org
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[Floimair Florian]

Thanks Josh!

I went the same path actually but gave up, as CSS to me is something completely 
out of my knowledge domain.
I also had a look at the other teams but so far Material for mkdocs does still 
look like the best option out there readily available.

Best regards

FLORIAN FLOIMAIR
Development
Symphony Cloud Services
Commend International GmbH
Saalachstrasse 51
5020 Salzburg, Austria
Phone: +43 662 85 62 25
Mail: f.floim...@commend.com<mailto:f.floim...@commend.com>
[signature_1049423312]
commend.com
LG Salzburg / FN 178618z


Von: asterisk-dev  im Auftrag von Joshua 
C. Colp 
Datum: Mittwoch, 9. August 2023 um 16:25
An: Asterisk Developers Mailing List 
Betreff: Re: [asterisk-dev] [External] Re: Final Preview: docs.asterisk.org

CAUTION: This email originated from outside of the organization. Do not click 
links or open attachments unless you recognize the sender and know the content 
is safe.
On Wed, Aug 9, 2023 at 11:12 AM Floimair Florian 
mailto:f.floim...@commend.com>> wrote:
Just to be precise: By “template” I meant the “Material theme” that is used.
I honestly don’t like it for exactly that reason. To me it seems this is 
optimized for vertical displays rather (e.g. mobiles) rather than being truly 
responsive.

I can't find anything quickly within the reference documentation for the 
material theme[1] or mkdocs[2] for it explicitly, aside from overriding 
HTML/CSS probably. If someone wanted to explore that then they could locally 
and propose it as a PR. The same goes for an alternative theme that we should 
use instead.

[1] https://squidfunk.github.io/mkdocs-material/reference/
[2] https://www.mkdocs.org/user-guide/

--
Joshua C. Colp
Asterisk Project Lead
Sangoma Technologies
Check us out at www.sangoma.com<http://www.sangoma.com/> and 
www.asterisk.org<http://www.asterisk.org/>
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[Joshua C. Colp]

On Wed, Aug 9, 2023 at 11:12 AM Floimair Florian 
wrote:

> Just to be precise: By “template” I meant the “Material theme” that is
> used.
>
> I honestly don’t like it for exactly that reason. To me it seems this is
> optimized for vertical displays rather (e.g. mobiles) rather than being
> truly responsive.
>

I can't find anything quickly within the reference documentation for the
material theme[1] or mkdocs[2] for it explicitly, aside from overriding
HTML/CSS probably. If someone wanted to explore that then they could
locally and propose it as a PR. The same goes for an alternative theme that
we should use instead.

[1] https://squidfunk.github.io/mkdocs-material/reference/
[2] https://www.mkdocs.org/user-guide/

-- 
Joshua C. Colp
Asterisk Project Lead
Sangoma Technologies
Check us out at www.sangoma.com and www.asterisk.org
-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev

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

[Floimair Florian]

Just to be precise: By “template” I meant the “Material theme” that is used.
I honestly don’t like it for exactly that reason. To me it seems this is 
optimized for vertical displays rather (e.g. mobiles) rather than being truly 
responsive.

FLORIAN FLOIMAIR
Development
Symphony Cloud Services
Commend International GmbH
Saalachstrasse 51
5020 Salzburg, Austria
Phone: +43 662 85 62 25
Mail: f.floim...@commend.com
[signature_646497160]
commend.com
LG Salzburg / FN 178618z


Von: asterisk-dev  im Auftrag von 
Floimair Florian 
Datum: Mittwoch, 9. August 2023 um 16:05
An: Asterisk Developers Mailing List 
Betreff: [External] Re: [asterisk-dev] Final Preview: docs.asterisk.org

CAUTION: This email originated from outside of the organization. Do not click 
links or open attachments unless you recognize the sender and know the content 
is safe.
Hi George!

Something I noticed (e.g. on this page: 
https://docs.asterisk.org/Asterisk_20_Documentation/API_Documentation/Module_Configuration/res_pjsip/)

The available space in the browser is used badly with the current layout 
template.
There is a lot of blank space to the left and right, while the important 
content of the tables in the middle is in fact cropped and the browser even 
shows a horizontal scrollbar for the middle part.

I am using a 16:9 display so I guess I am not that exotic in the way the 
content is presented to me.

Can we somehow make better use of the space? E.g. make the left and right 
sections (left: “Asterisk Documentation”, right: “Table of contents”) static to 
the left and right and use whatever space is available for the main content in 
the middle.



FLORIAN FLOIMAIR
Development
Symphony Cloud Services
Commend International GmbH
Saalachstrasse 51
5020 Salzburg, Austria
Phone: +43 662 85 62 25
Mail: f.floim...@commend.com
[signature_2176956728]
commend.com
LG Salzburg / FN 178618z

-- 
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev