Skip to main content

Mariano Guerra's Log

This is my blog, more about me at marianoguerra.github.io

🦋 @marianoguerra.org 🐘 @marianoguerra@hachyderm.io 🐦 @warianoguerra

Improving Official Erlang Documentation

Many times I've heard people complaining about different aspects of the Official Erlang documentation, one thing that I find interesting is the fact that the Erlang documentation is really complete and detailed, so I decided to dedicate some time to other parts, to get familiar with it I decided to start with an "easy" one, it's presentation.

So I downloaded erlang/otp:

git clone https://github.com/erlang/otp.git

And did a build:

# to avoid having dates formated in your local format
export LC_ALL="en_US.utf-8"
cd otp
./otp_build setup
make docs

Then I installed the result in another folder to see the result:

mkdir ../erl-docs
make release_docs RELEASE_ROOT=../erl-docs

And served them to be able to navidate them:

cd ../erl-docs
python3 -m http.server

If you want to give it a try you need to install the following deps on debian based systems:

sudo apt install build-essential fop xsltproc autoconf libncurses5-dev

With the docs available I started looking around, the main files to modify are:

lib/erl_docgen/priv/css/otp_doc.css

The stylesheet for the docs

lib/erl_docgen/priv/xsl/db_html.xsl

An XSLT file to transform xml docs into html

The problem I found at first was that to see the results of my changes to db_html.xsl I had to do a clean and build from scratch, which involved recompiling erlang itself, taking a lot of time.

Later I found a way to only build the docs again by forcing a rebuild:

make -B docs

But this still involves building the pdf files which is the part that takes the most time, I haven't found a target that will only build the html files, if you know how or want to try to add it in the make file it would be great.

With this knowledge I started improving the docs, I will cover the main things I changed.

You can see all my chages in the improve-docs-style branch.

Small styling changes

  • Don't use full black and white

  • Set font to sans-serif

  • Use mono as code font

  • Improve link colors

  • Improve title and description markup on landing page

  • Update menu icons (the folder and document icons)

  • Improve panel and horizontal separator styles

  • Align left panel's links to the left

Improve code box color, border and spacing

/galleries/misc/otp-old-2.png

Old Code Examples

/galleries/misc/otp-new-2.png

New Code Examples

Improve warning and info boxes' color, border and spacing

/galleries/misc/otp-old-3.png

Old Warning Dialog

/galleries/misc/otp-new-3.png

New Warning Dialog

/galleries/misc/otp-old-4.png

Old Info Dialog

/galleries/misc/otp-new-4.png

New Info Dialog

Logo Improvements

  • Remove drop shadows from logo

  • Center Erlang logo on left panel

  • Erlang logo is a link to the docs' main page

  • Put section description after logo and before links in left panel

/galleries/misc/otp-old-1.png

Old Landing Page

/galleries/misc/otp-new-1.png

New Landing Page

Semantic Improvements

  • Use title tags for titles

  • Remove usage of <br/> and empty <p></p> to add vertical spacing

  • Use lists for link lists

  • Title case section titles instead of uppercase

  • Add semantic markup and classes to section titles and bodies

  • Add classes to all generated markup

    • The ones I couldn't figure out a semantic class I added a generic one to help people spot them in the xsl document by inspecting the generated files

  • Clicable titles for standard sections with anchors for better linking

Improve table styling

/galleries/misc/otp-old-5.png

Old Tables

/galleries/misc/otp-new-5.png

New Tables

Improve applications page

/galleries/misc/otp-old-7.png

Old Applications List

/galleries/misc/otp-new-7.png

New Applications List

Improve modules page

/galleries/misc/otp-old-8.png

Old Modules List

/galleries/misc/otp-new-8.png

New Modules List

Add "progressive enhanced" syntax highlighting

At the bottom of the page there's a javascript file loaded, if successful it will load the syntax highlighter module and css and then style all the code blocks in the page, if it fails to load, is blocked or no js is enabled then the code blocks will have a default styling provided by CSS.

The markup was not modified in any way to add this feature.

Make code tokens easier to differentiate from standard text

The previous style for inline code was a really light italic font, I changed it to monospace but it was hard to distinguish, so I got some inspiration from slack and surrounded the inline code words in a light box to make them stand out.

Indent Exports and Data Types' section bodies

/galleries/misc/otp-old-6.png

Old Data Types and Exports Sections

/galleries/misc/otp-new-6.png

New Data Types and Exports Sections

This is all for now, I have some other ideas for future improvements but they involve changes to the documentation so I will submit them separatedly.

If you have any feedback please let me know!