Make docs more readable and user-friendly

Currenly texts in docs may have too long lines like this:

its not pretty good for reading.

But if we will limit string to 7-10 words it will be more readable, see:

Just do #staticContent p { max-width: 40em; }

If you prefer shorter lines you could just make your browser narrower

1 Like

Nice advice =)

I mean just text. Not code examples or images.
Feature with limit words in string come from typography.

They have many adivce how we can make text more readble, but for me length of string seems more terrible.

1 Like

After my comment I did some research and found Readability: the Optimal Line Length - Articles - Baymard Institute which also confirms a line length of around 45 - 75 characters for readability.

Let’s see if others comment.

1 Like

Let’s just make our font bigger. (Ha I’m sure it’s more involved then that)

I remember back in the day doin dynamic layouts that used some small view width value as the text size value. For the most part it would keep the same amount of text on screen at any given time no matter the browser size. (This was before mobile support considerations)

1 Like

All good for me! Feel free to send a PR

Sometimes we just have to add a line break into the markdown pages to make them more readable, it’s easy to do even if you don’t know how Github works.

From your example:

Meshes can be deformed by using morph targets. A morph target must be built from a mesh with the **EXACT** same number of vertices as the original mesh.
Morph targets are used by the GPU to create the final geometry by applying the following formula:
  • by:
Meshes can be deformed by using morph targets. A morph target must be built from a mesh with the **EXACT** same number of vertices as the original mesh.

Morph targets are used by the GPU to create the final geometry by applying the following formula:

I just have to press Enter here, and it’s already more airy :slight_smile:

In this cas we can even use code tag ` and list, we get:


Meshes can be deformed by using morph targets. A morph target must be built from a mesh with the EXACT same number of vertices as the original mesh.

Morph targets are used by the GPU to create the final geometry by applying the following formula:

final mesh = original mesh + sum((morph targets - original mesh) * morph targets influences)

For instance, you can use morph targets to simulate the opening of a mouth:

  1. The initial mesh has a closed mouth. The morph target can be the same mesh but with an opened mouth.
  2. Then by changing the influence of the morph target (from 0 to 1) you can display either a closed or an opened mouth, or a mix of both.

Thats not too good. Imagine this on large screen like 2K+, event on the FullHD it will be strange.
My main work is creating websites, and I have some skill with it and with formatting text for pretty reading. We tried approach with relative font size and it was not good.

Yes, and for it purpose also may set larger line height.
Compare that, before:

and after:

I don’t think this issue should be solved by using linebreaks. This is a style issue that should be solved in css.

edit: I think I misunderstood vinc3r. What he is describing is adding paragraphs in markdown - not linebreaks.

2 Likes

A little bit trickier than this since .scss and .pug are involved

… and use more pictures, please. i’ve clicked on the same sandbox examples several times in the last months.

Well, yes. If scss is used, then update the scss with your css.

Now I have remembered that ‘grunt sass’ compiles the scss files it is not as big a problem as I thought.

Just restricting the width of a paragraphs gives a couple of issues

multiple images on one line become one image per line, bullets points are not affected. More time needed and I have no more today.

Yep, not native english speaker here :sweat_smile: And I was talking about markdown tweaks just because it’s easy to do by anyone. I was once tried to understood how the doc’ css can be modified, that was a failure ahah, because of this scss thing.

:slight_smile: Yep, control-mousewheel… I love it. I use it for forum-reading, too. Font-sizes for old people eyes… yay!

For all readers, not just @Pryme8

Hey mobile device users… got mousewheel? Got control button? Got a useless piece of crap in your hands?

Whatever happens here, let’s NOT start styling primarily for mobile devices… like the news services are leaning-towards, these days. Instead, demand that the mobile devices get control-mousewheel power.

Perhaps offer pick-a-style. Main thing, please don’t force mobile-device-styling… onto us desktop readers. Keep your walkie talkies out of our way. We desktoppers were here first, and for a MUCH longer time-span. :slight_smile:

Aside: I’m test-driving that rant. :slight_smile: I’ve never tried it before… not many opportunities. I’m trying to create a war between the mobiles and the desktops… and create a personal internal conflict for those who use both. heh.

This IS a line-length issue and not a sentence-length issue, right? The topic is a little wobbly. :slight_smile: (Notice my heavy-use of ellipses… for long sentence management.)

Are we ACTUALLY suffering from too much text… due-to not enough “a picture tells a thousand words” diagrams? And/or… lack of multi-lingual docs? And/or… lack of multi-lingual playground-based tutorials? I dunno.

@Wingnut the mouse wheel is genius. I’m telling you modern browsers require modern solutions.

Hahaha

1 Like

heh. I think mobile devices need CONTROL buttons even more than wheels. AND alt, and meta, and shift buttons… because this opens their world to control-swipe, alt-pinch, shifted touch, ALL the gestures get more options/power.

Anyway, mobile hardware design is WAY off-topic, I suppose. :slight_smile:

I’m pretty sure chrome does that. You hold alt or something and scroll the mouse wheel it should scale the text size.

I’ll look that up really quick.

Ok it’s ctrl-mouse wheel or +-

Yeah, I use control-mousewheel ALL THE TIME, in FIrefox. Big fonts are happy fonts… making miserably-complicated reading about shadow precision… happier. :slight_smile:

But… no shift/alt/meta/control buttons on mobile devices (that I know-of)… so they don’t have a control-swipe to make THEIR fonts bigger … with/without text re-wrap.

Too bad we lost text coloring in the new forum posts… cuz… I like tooty-frooty colors, too (esp in docs-authoring). I live on Sesame Street. :slight_smile: Rainbow-text is tough, though… when allowing light and dark themes. Off-topic, sorry.

Sometimes I’m a little lazy, so… img :smiley:
Off-topic but about reading long texts on computer, notice the “read mode” icon (F9 key) on the left :wink:

1 Like