Documentation format issues

[J3RN]

Having good documentation is an import responsibility of any programming language, especially one hoping to provide good DX. While the Gleam documentation format is quite good, and in some areas is better than any other format I could find, it falls short in a few other areas. What follows is a discussion of issues with the current format and recommendations on how they might be fixed based on research into the documentation formats of other programming languages. These issues are listed from most important to least.

• "Functions" and "Types" sections are appended to the bottom of the left-side bar. On smaller screens, these may be rendered off-screen and the reader may not be aware they exist at all. Even if the reader realizes they exist, they will likely have to scroll to find what they're looking for.

  Llanguages that provide convenient in-page navigation form two camps:

  1. Elixir-style tree/accordion sidebar.

     

     The sidebar features three tiers: Modules, Sections, Members. The interface has a "drill-down" mechanic where you click a Module name to see its Sections, then click a Section to see its Members. Go also uses this format, Ruby/Rubydoc uses a similar accordion/tree structure for drilling-down through namespace hierarchies.

  2. Clojure-style right-side bar.

     

     The left-side bar features a list of modules (called "namespaces" in Clojure) whereas the right-side "Table of Contents" box contains Sections (e.g. "Types") and Members (e.g. "Vec"). This style is also used by Dart, .NET, Typescript, and inconsistently by Django, Kotlin, and others.

  The sun/moon light-mode/dark-mode toggle also suffers from being off-screen at the bottom of the sidebar; could afford to be relocated.

• Space utilization. While many other documentation formats suffered from too little whitespace and appearing jumbled, Gleam's documentation format sometimes struggles to fit content into the viewport.

  

  Upon review, I found four specific issues:

  1. Permanent, mostly empty header bar
  2. Large font for function names
  3. Large gaps between functions
  4. Content is narrow (not conveyed well by image taken on a small laptop screen 😅)

  At 680px, the actual content section of Gleam's documentation format is narrower than all others surveyed with the exception of Clojure's. Another item taking up significant space is the "chase"; the pink squiggle under titles. However, this adds a nice character to an otherwise rather sterile page, and so I don't recommend changing it.

  Recommendations:

  1. Move current header bar content into the left-side bar, remove the header bar.
  2. Reduce function name font size
  3. Reduce gaps between functions
  4. Widen content section slightly. The content section width of other formats is generally >750px (Elixir's is 829px, Rust's is 936px).

• Search. Almost every format, including Erlang's own rather minimal format, feature a search functionality (exceptions: Clojure, Node.js, Deno). While today's Gleam packages are small and easy to navigate, this might not stay the case, meaning that a search feature may become immensely useful.

• Lack links to module source. The only languages surveyed whose documentation format included this feature were Elixir and Rust. However, being able to jump to a module's source code rather than to one of its types or functions is useful.

• Packages cannot specify a logo image. The only language surveyed that provides this functionality is Elixir (e.g. Ecto). However, I feel that it gives a nice, personal touch to documentation pages.

[lpil]

"Functions" and "Types" sections are appended to the bottom of the left-side bar.

It would be good to improve this, but I don't think that Elixir or Clojure are good ones to copy. I am consistently confused by the behaviour of the Elixir sidebar, and I just tried Clojure's docs and they don't work at all on mobile.

It may be good to look at the sidebar of the upcoming Elixir redesign.

Permanent, mostly empty header bar

If we remove this we'll need a new way to open the menu on mobile. I'm not entirely sure I understand the advantage of removing it though, it's very small and many websites including the one we're using right now have a sticky header. What would you say is the problem created by the header?

Large font for function names
Large gaps between functions

What is the issue that this provides? The function names are designed to make it clear where one item begins and another ends. It doesn't make it difficult to read a single function (I would say it helps), and it doesn't change how you would get to a function with the sidebar or search. I found most the linked docs notably harder to read than Gleams as I found it harder to identify where each item ended.

I could see that it would make you scroll more if reading documentation top to bottom, but I've been doing that this morning as a test and I've not found that annoying at all. Perhaps I'm missing something?

Widen content section slightly. The content section width of other formats is generally >750px (Elixir's is 829px, Rust's is 936px).

The width has been selected based upon accessibility guidelines for legibility, and we actually are on the wider end of the recommendation. As someone with dyslexia I found most those you shared harder to read, except Clojure and Deno which use similar character widths.

Deno is wider in pixels but uses a large font size. Is this preferable? It shows less information on the screen overall.

Search

We want this for sure. I seem to have turned the issue into a discussion for some reason, though I'm not sure why...

#1342

Lack links to module source

We have this so long as you have filled in the repository information in your gleam.toml

We can't really jump to a module's declaration like Rust as Gleam doesn't have module declaration statements. We could have a link to the top of the page perhaps?

Packages cannot specify a logo image

Sounds good, we can do this too.

[michallepicki]

About Space utilization:

I think many of the raised points are personal preference and unfortunately it'll be hard to make everyone happy...

Move current header bar content into the left-side bar, remove the header bar.

I don't mind the header being at the top, a good thing about it is that it's an always accessible link to the main page of package's docs, e.g. if you were browsing and scrolled far down on mobile. Is the issue that you think it takes too much vertical space? Maybe on mobile its height could be a bit smaller?

Reduce function name font size

I personally like the current size :)

Reduce gaps between functions

The spacing from the screenshot "feels" off to me because the section header e.g. Functions has a decoration underneath, and then some space, but between functions the spacing is the same (size of underline is not subtracted). So spacing looks perfectly fine under the Functions header but big in between functions. I personally agree I would reduce the gaps slightly wherever there is no decorations under heading.

In general, how about adding more customizations?

Spacing & width personal preferences could persist e.g. in local storage. I added some limited width, line spacing and font controls to my blog this way for fun once (click the palette icon in the top right and play with different + - links). Maybe there could be a toggle for narrow and wide content width, and a second toggle for normal and compact spacing?

[J3RN]

"Functions" and "Types"

Sadly, Elixir's new documentation format keeps the same mechanic, but adds + and ^s to indicate which things can be expanded:

I guess it may be more intuitive but, for me, is a bit visually confusing at first glance.

Clojure was probably a bad example, as their documentation format suffers from a number of other issues. You might consider viewing the .NET docs as an alternative implementation of this style.

In all implementations of the right-side navigation bar I found (Clojure aside), it is not rendered at phone viewport sizes simply because there isn't space for it. Sometimes the "Table of Contents" is moved to the top of the page. Then again, I'm not sure how many people are reading reference documentation on phones.

Permanent, mostly empty header bar

Content is narrow

The overriding theme between these is simply that these items create dead space on the page, with the narrowness of the content being most apparent when viewed in a full-size browser window (simulated as 1620px wide).

Perhaps some of that space off to the right could be used for an in-module/in-page navigation feature? The downside, of course, is that any new content placed off to the right may have to be hidden/removed at smaller viewport widths.

Large font for function names

Large gaps between functions

The theme between these was that less content can be viewed at once; more scrolling, as you said. I don't feel particularly strongly about this. As @michallepicki noted, I think the spacing between functions "feels" a bit weird, we might be consider tweaking a bit.

We could have a link to the top of the page perhaps?

Yes, sorry, this is what I meant: Having some link at the top of the page that just links to the whole source file.

[J3RN]

I created a functional prototype for what the Gleam documentation format would look like with a right-side "table of contents":

It's fine, still very open to other ideas for in-page navigation.

[lpil]

That could help a lot! We need to ensure we still have a good experience on mobile.

Another option could be to have the different sections expand and collapse, similar to the new version of HexDocs

[J3RN]

I've deployed a slightly touched-up version here: https://j3rn.com/gleam_stdlib_right_nav/gleam/base.html

Notes:

• Similarly to other right-side navs, it disappears when the viewport is too small
• On shorter screens, you can wind up with a scroll bar for both the left and right nav. It's not the worst thing I've ever seen, just throwing it out there:
  

---

I can try do the accordion-style tonight. I'll have to dust off my JavaScript skills 😅

[lpil]

I would like to avoid having features that only work on wider displays, so we'll need to have a way of viewing the function list still when on smaller viewports.

It is also possible with this layout to partially hide the bar, we should show it entirely or reposition it.

I'm not sure about the light coloured background, to me it doesn't seem in keeping with the rest of the visual design.

Having the pages + links + modules sections be collapsible may be easier than adding a new UI element.