as part of my day job i have to develop new features based on UX mockups created by our design team and shared using invision, an online prototyping tool. this gave me a thought - what if we used this idea for documenting grid based apps?
instead of static images and a wall of text we could have interactive documentation which would to some extent mimic what the actual app does, and therefore be much easier to understand and learn. i’ve put together this quick prototype to give an idea of what it would look like (using orca’s heart app):
click on various buttons to see what they do. if you click on a button that is not currently mapped, it’ll highlight the areas that are clickable. this is just a simple example that doesn’t do much. one thing i don’t like about invision implementation - you have to click somewhere to determine which areas are clickable, and i don’t see a way to make it show tooltips when moving mouse over.
i haven’t checked other similar tools, which might work better for this purpose, but: 1) they are meant for building any custom designs, so an overkill 2) we would depend on that service. what if we build our own tool instead? this is my challenge:
create a lightweight javascript tool that would work as interactive documentation for grid based apps
keep it simple, no visual editor, it could consume json/yaml/custom format file describing the app
the doc would describe all the various screens
have the option to highlight some buttons (background colour / frame) and apply text labels
apply actions to buttons - switch to different screen / show description / show animation
simple animation - highlighting buttons in sequence to describe some actions
i’m thinking something very minimal for start and something that could be easily hosted / would play well on tablets / offline. is somebody willing to take on this challenge? (the reason it’s a challenge is because i have very little knowledge of js, especially the latest frameworks, and have no idea of how feasible this is).
yeah, could definitely be used for module tutorials as well - but intentionally limiting the scope for now, since documentation for grid apps tends to be a lot heavier due to multiple app pages. and it’s a real pain point imo both for users and for developers - if you look at various app manuals you’ll see many different styles - we are reinventing the same wheel over and over again.
as-is, this is great as a quick reference. it’s quite nice having all of the functional layers available in a single tool, and the process of navigating through potentially develops/reinforces muscle memory.
if i were approaching an app for the first time, a bit of text/description would be helpful (i think you were suggesting this under simple animation). i guess i’m thinking, for example, of the matrix screen and knowing what the various routings affect.
Love this idea @scanner_darkly! I was definitely thinking of something similar with my compass documentation, but my (relative) inexperience with front-end stuff meant my interactive example was painstakingly (and goofily) created via a bloated svg. I’m embarrassed at how long it took to create that thing
To anyone interested in taking on the js work, I’m happy to provide design help if it’s helpful!
yeah, definitely - the area under the grid could be used for accompanying text description or additional images (like norns screens). another text area could present detailed info about particular buttons.
your doc looks amazing! it’s quite incredible how much time a good manual takes (and it’s the least favourite part of developing an app for me). so anything that would simplify it would mean we’d have more time for more dev.
yeah in some ways you are recreating keypress / grid refresh code, so i thought about re-using existing code but i think there are sufficient differences in that you’d still have to do some translation, so not sure it’s worth it. so yeah, keeping it super simple - i’m thinking maybe something like a python script that takes a text template and converts it to js/html (so, not using js to convert the template).
input could be something like this:
page:
id: main
title: Main Screen
buttons:
- button:
x: 15
y: 0
action: page!options
tooltip: press here to open options
page:
id: options
title: Options
buttons:
- button:
x: 15
y: 1
action: page!main
tooltip: press here to go back
agreed. doing a simple css grid based layout of divs, having the js add/remove data-attrs or classes which dictate the css is really all you need.
page:
id: main
title: Main Screen
buttons:
- button:
x: 15
y: 0
action: page!options
tooltip: press here to open options
page:
id: options
title: Options
buttons:
- button:
x: 15
y: 1
action: page!main
tooltip: press here to go back
I like the idea of yaml config, the thing that I’m trying to figure out fi there is an elegant way to make this terse as I feel like this would get reallyyyy long if each button for a particular page was specified
EDIT: maybe instead of buttons being the object you expose at the page level, you make actions…then have some way(s) of associating buttons (ranges of buttons) to this object. action function and tooltip could get x/y as params to be used. this way you only have as many top level objects as there are different types of actions on your page, which is usually a handful. as opposed to buttons, which you could have all 128 doin something
yeah, agreed, would be good to keep yaml more terse!
re: buttons - yeah, the idea is that you would only describe buttons that have actions assigned to them, but making actions the main element makes more sense since you could have an action assigned to a group of buttons.
exactly! basically, a yaml file + js engine. and i’m thinking, instead of using python script to parse yaml we could probably just parse it in js - this way we could build a visual editor at some point, and yaml parsing should be pretty lightweight.
also thinking not having separate pages but just re-rendering dynamically when navigating to a different page?
out of curiosity tried building a script that renders an empty grid
<!DOCTYPE html>
<html>
<head>
<style>
div {
width: 28px;
height: 28px;
border-style: solid;
border-width: 1px;
background-color: #ffffff;
position: absolute;
padding: 0;
margin: 0;
border-radius: 3px;
}
</style>
</head>
<script>
function create_button(x, y) {
var div = document.createElement('div');
div.id = x + '_' + y;
var posx = x * 46;
var posy = y * 46;
div.style = 'top: ' + posy + 'px; left: ' + posx + 'px';
return div;
}
function create_grid() {
var body = document.getElementsByTagName('body')[0];
for (var x = 0; x < 16; x++)
for (var y = 0; y < 8; y++) {
var div = create_button(x, y);
body.appendChild(div);
body.insertBefore(div, body.firstChild);
}
}
</script>
<body onload='create_grid();'>
</body>
</html>
Was thinking it’d be cool if there was a js script to convert between the yaml and a vanilla html/css (style tags)/js (script tags) blob. That way you could easily copy and paste that blob and have the working thing without having to set up any sort of tooling.
Also would not be hard to run that conversion js script in node (maybe package it up in a tiny little cli) and also have it run on the web that uses it to convert to the grid in real time like codepen
I estimate that this interactive doc is mainly intended to be used for norns as I read the posts.? I only have expirience with grid-Teletype integration. For this it would be also great and perhaps opens the topic for more users more easily as learning the code with a interactive connected virtual grid tool which perhaps highlights specific code lines/areas at button presses. I estimate this could also be true for norns users and would not only help to learn an app / script faster but, in my opinion even more important, also allows learning the code increadibly faster, which opens systems to more people.
Do people have opinions on whether or not this proposed tool should centralize all of the grid app files? My brain just made a comparison to the way folks submit their norns scripts to the maiden project manager. If these interactive grid files stem from a template with clear design conventions, it could be neat to have them collected in a single location with an easy way to switch between them. No idea if that would dramatically complicate things from a dev standpoint, though.
no, not meant for norns only - any grid based app really, and i see it being used for specific grid teletype scenes.
emulating teletype would be significantly more complex though. but i can see this being a good companion for teletype grid studies, with maybe some examples of scripts presented with an interactive grid.
this definitely makes sense. i’m thinking we could also create a repository for yaml template files so that it’ll be easy for people to contribute to docs as well.
