[Usability] Function headings are not clear

[eksperimental]

I am having a hard time trying to spot where the functions begin.
I think we need to make clear where a function ends and where a new one starts..
Please, have a look at this screenshot.

I know where Example Starts,
and the second Example begins.
but to my tired eyes, it looks like intersperse belongs to the top Example, when it is sort of the opposite.

WDYGT

[josevalim]

Others have mentioned this too. One approach is to reduce the headers size inside the functions themselves.

[dignifiedquire]

I think the solution is two fold. First reduce the size of headers like Examples to the same size as Specs, second add some indentation of the content inside the function block so the function header stands out more

[eksperimental]

seriously combining this issue with the fact that visiting the internal links from the search does not take you exactly where it should, It's impossible to spot the functions.. i end up going to the sidebar and clicking there.

one solution, maybe is give move white space after each funcion.
another... maybe it won't look good, but it can be something along those lines.. is to extend the blueish block so it sticks out to the left marging so it can help you visually identify where these function headings are..

[eksperimental]

a solid horizantal divider ala <HR>, may help as well. sorry guys. my designing skills are horrible. ;-P

[josevalim]

@dignifiedquire we need to support h1 + h2 (they could have exactly the same size as docs are not meant to have h1), h3 and h4.

[DanCouper]

Just to add to the discussion, I'd agree with @eksperimental on all counts. Here are two screenshots:

I'm reiterating points, but there a. isn't enough whitespace between the function sections (and a horizontal divider may be helpful in addition to increasing the gap), and b. the headers don't delimit the sections properly - they simply don't stand out compared to the headers for the examples, which makes scan-reading very difficult. I'd extend this criticism to the @moduledoc section, and the generated summary - there isn't enough typographic/layout differentiation between the different module sections, and at a more granular level between the sections under each function.

The design is just about there (and it's beautiful), but it doesn't scan half as well as the original (much uglier) docs.

[josevalim]

The spacing suggestion is a good one. Adding the spacing and reducing the headers font-size will be likely enough to solve this completely. :D

[DanCouper]

I'd agree with that :)

[eksperimental]

one good point that @DanCouper made is that the function HEADER, looks like inline code.
having a background color similar to the ones in the code examples make it difficult to stand out.
maybe with a bigger font, it won't look like code anymore.. we'll see

[edmz]

I was just going to submit an issue for this. Its good to realize that I am not the only one for who this is important.

My gripes have already been addressed here by eksperimental and dancouper.

[milmazz]

I haven't test this, but, the current size of the function signature header is 1rem and the level 2 headings (h2) inside of the .docstring sections are 1.625em (that's why the Example header is bigger than the function header, for more details please review content/general.less), I think this could be solve if we add the following at the end of assets/less/content/functions.less file

.docstring {
  h2 {
    font-size: 0.95rem;
  }
}