Rounding off my second week of work on L5! This week focused heavily on the design and beginning implementations of documentation, as well as seeing some of the tensions on first-time users.

Recap

If you missed the first post:

Based on the schedule outline

TLDR;

New L5 Website Feature Request

The previous feature request issue template was a little wonky and had some duplicate issues, so went through and cleaned it up using a Github Template Form.

It now looks sleek :)

You can see my notes on the PR here:

https://github.com/L5lua/L5-website/pull/23 External Link • github.com

Usability Studies

There were two usability studies conducted by the University of Washington prior to my work with GSoC

From these studies, they had a few suggestions, varying from design suggestions to updates of the general flow. Given a strong starting point for design and implementation, I broke them out into several issues (using my new feature request form):

https://github.com/L5lua/L5-website/issues/24 External Link • github.com https://github.com/L5lua/L5-website/issues/25 External Link • github.com https://github.com/L5lua/L5-website/issues/26 External Link • github.com https://github.com/L5lua/L5-website/issues/28 External Link • github.com

Right now, not everything covered in the usability studies is necessarily fixed by written documentation but these created issues prioritized that.

Things that will be fixed in another repository:

Things that might not be addressed as a constraint of Lua:

Design Suggestions

The experienced usability studies also created some design suggestions.

Design Research

I spent most of this week on research, design, and prototype of the updated web design.

Now I grew up learning Processing; shifting to p5.js when I was in university. So I have a special place in my heart for the old p5.js reference pages.

p5.js landing page in October 2016 from https://web.archive.org/web/20161022185309/http://p5js.org/

p5.js landing page in 2020 https://web.archive.org/web/20200610233636/https://p5js.org/

Lee and I also discussed some other reference pages:

Current hydra docs: https://hydra.ojack.xyz/docs/

Current Arduino docs: https://docs.arduino.cc/

Current Lua docs: https://www.lua.org/

I have more bookmarked in nice code references on arena*:

https://www.are.na/sam-heckle/nice-code-txt External Link • are.na

Design Prototypes

I created these in penpot, an open-source alternative to Figma. It worked ok I think, but maybe I'm not getting the most out of it since I didn't make any prototypes or export CSS.

Landing Page Prototypes

Obviously these come from heavy inspiration from the original p5.js and Lua pages.

Navigation Updates

In retrospect I did not need to make these massive images and probably could have made a sitemap of the navigation.

Design Discussion

From there, Lee and I had a conversation about which designs worked best and went to set up the L5 blog.

We kind of concluded that the landing page* was unnecessary, but curious about others! Let's see how this Leaflet poll goes:

I also made this cute low-bandwidth badge using https://web.badges.world/

Uncertain if it will actually end up on the documentation site but if you have ideas let me know!

Design Implementation

After completing the designs, I began work on implementing them using our SSG MkDocs. I haven't used it before (but I have a pretty large are.na channel on blog tools), but figured out I needed some plugins to modify the navigation.

An open conversation we are having is whether or not to include some of these Mkdocs plugins due to site bloat. Right now, the live site runs ~850kb. My implementation makes each page ~1MB, so it increases by 200kb.

Mkdocs builds on Python Markdown, which has some extensions that allow for these nice toggles. Unfortunately, the way Mkdocs renders <detail> sections doesn't allow for markdown within the <detail>. The only way to enable it is to install an extension. Another blocker is that the entire webpage is rendered, instead of only rendering the visible components. If there was a way to force lazy-loading on these toggable-elements within Mkdocs...

Questions we are considering at this point:

Some other reference for low-bandwidth sites:

https://512kb.club/ External Link • 512kb.club https://1mb.club/ External Link • 1mb.club https://web.archive.org/web/20260602110640/https://ctrl-c.club/ External Link • web.archive.org

And some commandments for designing for low-bandwidth:

https://web.archive.org/web/20190215051701/https://aptivate.org/webguidelines/TopTen.html External Link • web.archive.org

Test my changes!

If you want to test my changes and see whats up, feel free to take a look and write feedback on this PR.

https://github.com/L5lua/L5-website/pull/27 External Link • github.com

L5 Blog Setup

Lee and I ran through some different blog options:

Unfortunately not a Leaflet, live to fight another day!

Lee and I ran a workshop yesterday at ITP Camp!

We had about 30 people in-and-out testing L5! Based off this experience, I think we are going to add higher priority on building out a VS Code extension.

Anyway

My friend Patrick got into boxing and is having his first exhibition match tonight! Good luck Pat!

xx smh