L5 Week 2 Round Up

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

Build out community guidelines based off of: p5.js community, ml5.js community, and permacomputing (including the L5 page on it).

Look at other open-source reference pages, such as Arduino, Hydra Live Coding.

Co-lead L5 workshop and surveying at ITP camp.

TLDR;

Updated feature request forms for github templates

Did a ton of research on the design, looking at other reference pages and pitches from the usability studies.

Created some test designs.

Implemented some designs on the documentation website that may have bloated the site too much, or it could have been because the pages are large now.

Created an L5 devlog on itch.io as we will be hosting an L5 jam later this summer. Lee wrote a very nice post about my first week. For some reason itch requires you to request to have custom CSS on your own pages, so I had to do that also?

Ran a workshop at ITP camp on Wednesday!

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:

created new formatted feature template form by samheckle · Pull Request #23 · L5lua/L5-website

Usability Studies

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

beginners to creative coding

experienced creative coders

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):

[Feature Request]: clean up homepage and getting started pages · Issue #24 · L5lua/L5-website

[Feature Request]: combine download and getting started menus to simplify installation process · Issue #25 · L5lua/L5-website

[Feature Request]: add bandwidth consumption to visual design · Issue #26 · L5lua/L5-website

[Feature Request]: update and reorganize parameters and syntax on reference pages · Issue #28 · L5lua/L5-website

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:

Live preview

macOS Security Override step

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

Embedded and interactive examples1

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 arena2:

nice code txt | 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 page3 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:

With the emphasis on low-bandwidth, are these extensions necessary?

Does the UX have precedent?

Some other reference for low-bandwidth sites:

512KB Club

1MB Club: A collection of web pages weighing in less than 1MB

Ctrl-C.club!

And some commandments for designing for low-bandwidth:

Web Design Guidelines for Low Bandwidth - TopTen

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.

Updates to Navigation by samheckle · Pull Request #27 · L5lua/L5-website

L5 Blog Setup

Lee and I ran through some different blog options:

Tried using Mkdocs blog plugin with an RSS feed.

Attempted creating and linking manual Markdown pages, but this required too much labor even for a post once a month.

Landed on an itch.io blog: https://notapipe.itch.io/l5/devlog 4

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

This is probably an entire project of writing a web-compiler for L5 and converting it to p5 for browser rendering.

yeah yeah i should migrate to semble

Referring to the first two screenshots under the design prototypes header without the large navigation bar on the left.

Unfortunately not a Leaflet (Lee doesn't have a bluesky). Because L5 has a build hosted on itch, it made sense.