Comfortable reading of the documentation

[Totktonada]

I want to share things that make my feelings of documentation reading process worse. The intention is to give feedback (hope it help with website design decisions) and is not for I-know-how-to-make-design holywars.

1. The page has three scrollbars: page scrollbar (but it does not affect anything, because can be moved only at pixel up/down or like so), navigation scrollbar and main content scrollbar. I need to place my cursor over navigation/content to scroll it, like it was with framesets in 2000s. Unusual (so, unexpected) behavious for modern web, annoing a bit.

2. The main content narrowed by panels and paddings: left padding + navigation panel, right padding, upper two-lines panel (website one + documentation one), bottom two-lines panel (website one + documentation one). It leaves non so many screen area for the content itself when I read the docs on my 13” laptop. I want to read the docs, not the panels content.

The chatlog (in Russian) where we discussed that feelings a bit.

2017-09-20 Alexander Turenko: Я, в целом, не напрягаюсь обычно от дизайнерских решений и не хочу вступать в полемику (и не вникал в предыдущие споры по теме), но у нас на странице с доками три скроллбара (если считать тот, что появляется для всей страницы и ничего не прокручивает). Раздельная прокрутка (kinda 2000-е и тег ) требует того, чтобы ты перемещал курсор над конкретным «фреймом» — обязывает к лишним действиям. Огроменные панели сверху и снизу отъедают (у меня) чуть ли не треть места по вертикали, что могла бы занять сама дока. Ощущения от пользования доками из-за этого не очень. Alexander Turenko: Хотя reading mode в ff с этим справляется, только навигацией не попользуешься. Konstantin Osipov: Огромные панели сверху и снизу это дань попыткам интеграции с Tarantool.io Konstantin Osipov: Ты не первый кто комплеится Konstantin Osipov: Если честно, я не понимаю, потому что экраны большие у все сейчас Konstantin Osipov: Но так как ты не первый, открой пожалуйста тикет, мы уберем нижнее меню из документации Konstantin Osipov: Двухуровневое Верхнее меню это тоже отсутствие решения которое бы устроило Тайлера Konstantin Osipov: Ему я и Костя говорили о том, что нужно сделать контекстное Верхнее меню в одну полоску Konstantin Osipov: Он это не принял Konstantin Osipov: Будем переделывать значит... Alexander Turenko: Окей. Alexander Turenko: Я думаю, что на это никогда нельзя расчитывать, поскольку сейчас планшеты занимают тот диапазон разрешений / размеров экрана, что раньше занимали небольшие мониторы. Ну и 13”-ноутбуки тоже не так уж велики. Alexander Turenko: Если неформально, то у меня складывается неуютное ощущение, что я смотрю документацию через квадратную трубу — так она стиснута полями и панелями со всех сторон. Roman Tsisyk: Я вчера ровно тоже говорил. Сейчас документации не юзабельна от слова совсем. Предлагаю убрать все панельки сверху и снизу asap.

[lenkis]

Observed at .org site, running Gentoo Linux + Firefox 57.0.1.

[lenkis]

Some bugs are gone in the new tarantool.io design (no 3rd pan-page scroll-bar, narrower paddings, scroll-away section header at the top, smaller font). Will discuss the remaining suggestions with @vlebedev. Thanks for the feedback!

[lenkis]

issues that still persist and can be improved:

Проблема 1: Раздельная прокрутка 2 левого и правого фрейма (kinda 2000-е и тег ) требует того, чтобы ты перемещал курсор над конкретным фреймом. Обязывает к лишним действиям.

Проблема 2: Двухуровневое Верхнее меню в разделе Developers отъедает место по вертикали. Нужно сделать контекстное Верхнее меню в одну полоску.

[lenkis]

problem 2 is now resolved at tarantool.io

[lenkis]

The remaining problem 1 is a matter of taste, indeed. It's about making both TOC (left frame) and content (right frame) stick together, like here: https://docs.python.org/3/library/re.html

Downside: you cannot e.g. scroll down TOC without loosing your current spot in the content frame.

Upside: easier navigation that implies using only scroll button / keyboard arrows / PgUp+PgDn.

To be discussed...

[Totktonada]

Now it is much better: the content takes most of the screen. I think there is nothing more to do within the issue. Thank you!

[Totktonada]

Now we again have a lot of panels: on top, at left and at right. It seems, the area for the documentation itself is about 1/2 of the webpage area (on a 14'' laptop).

The documentation is the most important part of a documentation page, isn't?

---

I also think that coalescing of the documentation website (former tarantool.org) and the enterprise website was the big mistake. As we all see, after ~4 years since this decision, the documentation is rendered poorly and slowly. The reason is that it is not just statically generated html, but rather inherit all the complex architecture of the enterprise website.

[patiencedaur]

https://github.com/tarantool/doc/issues/2742 will solve the problem. In particular, the text size and paddings will become smaller.

[Totktonada]

I guess I didn't described it well enough. I'll try to give more details below.

First of all, let's formalize the problem: area for the documentation on the documentation page is around 1/2 of the viewport area on my 13'' laptop screen.

Let's look why.

I think that the panel at the top should not follow scrolling (should not be positioned relative to the screen area). It just eats the viewport area without any gain comparing to static placement at the top of the page.

The right panel has a ToC of a current page, but I don't understand why we can't coalesce it with the ToC at left. BTW, the ToC at left is often collapsed and it hardens navigation.

The right panel also contains Found what you were looking for? [Yes] [No] block, but it cannot be a reason to spend 1/4 of the viewport area. If we need to collect some feedback, let's do it in a non-descructive way. At least hide it on laptop size screens (including HiDPI, of course).

Who is responsible for design of the documentation pages? It seems, we should start a dialogue.

Documentation pages in other projects for inspiration:

• https://docs.python.org/3/library/dataclasses.html
• https://etcd.io/docs/v3.5/faq/
• https://docs.python-requests.org/en/latest/user/quickstart/
• https://wiki.gentoo.org/wiki/Handbook:Main_Page
• https://www.postgresql.org/docs/14/datatype-numeric.html
• https://www.sqlite.org/lang_createtable.html
• https://redis.io/commands/get/

---

Current state:

[patiencedaur]

@Totktonada

We're requesting comments in https://github.com/tarantool/tarantool.io/issues/1024. Moved your comment there.