GUI improvement for documentation

ujovlado

Hi guys,

I was thinking about litte Documentation page improvement.

Here's proposal:

.

What do you think?

Also, I'm very familiar with CSS and if someone tell me where to do this change (if it will be approved), I can do it. ;)

s4muel

not bad! i would welcome a change like this.

but on pages like this: https://latte.nette.org/en/tags (no-wrappable table on left side and pretty high TOC on right side) the main content will get pretty narrow.
maybe if one of the side panels would collapse onclick/mouseover? or making the nette main column a bit more wide?

ujovlado

s4muel wrote:

not bad! i would welcome a change like this.

but on pages like this: https://latte.nette.org/en/tags (no-wrappable table on left side and pretty high TOC on right side) the main content will get pretty narrow.
maybe if one of the side panels would collapse onclick/mouseover? or making the nette main column a bit more wide?

Yes, I see, that big table at the beginning can be a problem. Showing “Contents” on right side on mouseover could be a solution. Thx.

Filip Procházka

It could show title of category the article is in, and related articles. There would be less noise.

in quickstart there would be chapters of quickstart
programmers guide articles would show the rest of them
…

hrach

I think we could make the default width of the site bigger. 940px is quite small and the target audience are programmers…

(Edit: Oh I see, you did it.)

David Grudl

Links to complete documentation on each page are needed, it is without a doubt. I was thinking about this concept http://www.mff.cuni.cz/fakulta/ (top menu). Something similar is here http://ellislab.com/…/user-guide/.

There is a problem with wider layout: layout should be the same size for all pages, otherwise it looks weird. That's why there isn't currently menu.

(OT: It would be great to do something like http://www.symfony2cheatsheet.com)

Vojtěch Dobeš

To be honest, I am not big fan of that top menu – maybe it is just because of these specific examples, but there is so much noise that it becomes difficult for me to actually read the topics. Maximum for me is that Symfony 2 cheatsheet, that is quite readable :). List of topics in sidebar is also easy to swallow – btw I always liked names of sections in Nette docs, because they were simple enough to get me interested in reading, during my first months with Nette I spent lot of time just reading through the docs and becoming amazed by the nice features it was describing.

hrach

To be honest, I am not big fan of that top menu

+1

Šaman

First draft looks good. I not like top menu too (and ecpecialy on wide monitor).

David Grudl

We all don't like top menus, I know. So suggest solution with left panel, TOC and content with current layout.

hrach

So suggest solution with left panel, TOC and content with current layout.

Sorry, I don't understand the meaning …

There is a problem with wider layout: layout should be the same size for all pages, otherwise it looks weird. That's why there isn't currently menu.

That's not exactly right. This is mainly caused by right alignment of the menu. However, I don't see any problem in suggested width for the whole website.

Filip Procházka

Hey, it's documentation, it's not supposed to look good, it's supposed to be readable and usable. I would try the wider layout

David Grudl

It must look good! :-)

Current width is ideal for all pages including forum, addons, homepage and documentation too. It can be little bit wider, but not much. And header must have always the same width. For documentation we can use wider #main (but not header).

ujovlado

I agree, it must look good. ;)

I'm working on prototype, please wait few days.

David Grudl

I redesigned header and expanded layout to 990px. I think it is maximum.

ujovlado

Ok, it's here: tmp.ujovlado.sk/nette-doc-proposal

I accepted those 990px and made small changes.

TOC is moved to content and its full content will show on mouseover.

So, what do you think?

To fill space in #left-navigation (that new left sidebar), there can be some element which will follow me, while scrolling down.

hrach

PR to PR:

preview: http://awesomescreenshot.com/03e28rwb6f
PR to PR src:

#left-navigation h2 {
	font-size: 1.7em;
	padding: 0 0 0 0.6em;
    margin: 0 0 .5em 0;
}

#left-navigation h2 img {
    width: 28px;
	margin: 4px 8px 0 0;
}

#left-navigation ul {
	margin: 0 0 3em 1em;
}

David Grudl

Vlado it looks really good!

But… :-) I've got idea. Wouldn't it be more useful (and usable) if the Content will be static? I don't know how to solve it. This is not ideal: http://postimg.org/…e/m3h6oqppd/

David Grudl

Example of side menu: https://doc.nette.org/en/forms (currently without TOC)

Example of static TOC: https://componette.org/search/?q=

ujovlado

hrach wrote:

#left-navigation h2 {
    padding: 0 0 0 0.6em;
    margin: 0 0 .5em 0;
}

#left-navigation ul {
	margin: 0 0 3em 1em;
}

Zero right margin (and padding) is not good idea. Some sentences are longer and looks weird when they're “pushed” on right border. ;)

ujovlado

David Grudl wrote:

Vlado it looks really good!

But… :-) I've got idea. Wouldn't it be more useful (and usable) if the Content will be static? I don't know how to solve it. This is not ideal: http://postimg.org/…e/m3h6oqppd/

Check this (TOC is static and visible after scrolling down)

tmp.ujovlado.sk/nette-doc-proposal-2

But, you need resolution about 1440px or greater …

Vojtěch Dobeš

Amazing improvements :)!

David Grudl

Vlado, it is not usable. TOC should be visible immediately.

ujovlado

David Grudl wrote:

Vlado, it is not usable. TOC should be visible immediately.

Yes, you're right (I did an update, please refresh).
Question is, where TOC should be placed if screen width is only 1024px :)

Pavel Macháň

My solution:

Activation by click on Menu icon+text

Hidden menu → Active menu

buffus

Excellent work, thanks.

A few ideas:

In the Programmer's Guide highlight the active link.
Eliminate differences between Link / Page title in Programmer's Guide, e.g.:

Forms / Forms – it is the same. I like this,

but these Link / Page title are different:

Templates / Templating
Helpers / Default Helper
Late Macros / Macros Default Latte
Configuration / Configuring
Extensions DI / DI Container Extensions
Controls and Components / Components
Routing / URL Routing
Authentication & Authorization / User Authorization and Privileges
AJAX / AJAX & Snippets
Table / Database \ Table
Selection / Database: Selection
ActiveRow / Database: ActiveRow
Mailing / Sending E-mails
Auto-loading / Class Auto-loading
Browsing files on disk / File Search: Finder
Validation / Nette \ Utils \ validators
Utilities for
- Strings / String Processing - Nette \ Utils \ Strings
- Arrays / Array Processing - Nette \ Utils \ Arrays
- URLs / Working with URLs - Nette \ Http \ Url

The differences between the link and page title can be confusing…

David Grudl

Another attempt: popup menu

ujovlado

David Grudl wrote:

Another attempt: popup menu

Nice, but I don't see any symbol/element saying “Hey, here are all links to documentation”. :)

Majkl578

David Grudl: That is really bad for bigger contents. It requires a huge vertical space to display whole content. In the case of page you linked, its over 820 pixels, which is more than average laptops have (not considering ~-100–200px taken by browser header, windows bar etc.). And it would look weird with scrollbar.

Filip Procházka

The popup menu isn't a bad idea at all! It could be bigger.

romiix.org

Bad TOC on netbooks.

David Grudl

We can create three columns.

Aurielle

If the fixed table of contents stays, could current section (the one currently scrolled to) be somehow highlighted in TOC?

ujovlado

David Grudl wrote:

We can create three columns.

Three columns in navigation pop-up or on whole documentation page?

David Grudl

Three columns in popup window ;-)

ad bad on netbooks: fixed
ad highlighting in TOC: je to tam

Filip Procházka

The scrollspy on the TOC is awesome!

Pavel Macháň

Show Popup on :hover action in main menu is so annoying for me :/

David Grudl

EIFEL wrote:

Hidden menu → Active menu

Good solution too. But little bit problematic with very long menu – if you want to click on any bottom link, you have to scroll on top, activate menu and scroll to down

David Grudl

I have an new idea, stay tuned :-)

Pavel Macháň

David Grudl wrote:

EIFEL wrote:

Hidden menu → Active menu

Good solution too. But little bit problematic with very long menu – if you want to click on any bottom link, you have to scroll on top, activate menu and scroll to down

Hmm… and what Floating menu icon as Forms right panel ?

David Grudl

Finished! (Of course, it will need tuning.)

hrach

Finished of course with you primary idea which was 3× "-1"ed. Collaboration win.

HonzaMac

It's broken from mobile phone/Opera Mini. Documentation menu hide Menu and it's not possible to click on anything from upper menu!

Vojtěch Dobeš

It is now impossible to click on the Documentation link itself.

Aurielle

It is possible from the forum, but not from the main site.

David Grudl

vojtech.dobes wrote:

It is now impossible to click on the Documentation link itself.

This is intentional.

Jan Tvrdík

What about

#docmenu.opened ~ #main {
	border-top-left-radius: 0;
	border-top-right-radius: 0;
}

?

David Grudl

@Jan Tvrdík +1

David Grudl

After few days od testing:

Original concept of side bar:

from some points of view probably best way
but adds a “text noise” to the page
it is inconsistent with rest of website, where sidebar is on right side
it's hard to combine with TOC, but there are drafts: http://postimg.org/…e/m3h6oqppd/ and better http://tmp.ujovlado.sk/…-proposal-2/

Hidden sidebar https://www.dropbox.com/…jlwnu/01.png and https://www.dropbox.com/…4ye4d/02.png

After testing I discovered that I am always clicking on Documentation instead of opening the bar

Popup menu (current solution)

solves noise, consistence, TOC
I am still not sure if I like it…

What do you think?

Filip Procházka

Current is awesome, let's give it few weeks/months :)