Web documentation design ideas and inspiration

[Olivier]

Thanks! I haven’t worked with Jekyll in a long time (and even then my experience was limited), but it would be fun to level up with @jlmitch5

[tehn]

now that i think of it, jekyll is not really the main issue. here’s the breakdown of the current doc sites:

• TT manual is generated i think by pydoc. it’s just html and seems like the css is inline: https://monome.org/docs/modular/teletype/manual/
• norns API is generated by ldoc and is similarly html but with a separate css: https://monome.github.io/norns/doc/
• norns github landing page is jekyll-generated: https://monome.github.io/norns/

i’ve been talking with @ppqq about how to properly structure norns docs, as there are four levels:

• basic intro/manual
• studies
• API reference
• programming manual (something that is somewhere between the studies and API reference, with small examples… which could perhaps be integrated into the API reference possibly, though it could be tricky given the API reference is generated from source tags)

[xenus_dad]

https://readthedocs.org/ ?

Curious if this would help at all with versioning and automation. Also thinking that while bespoke wheels are pretty and all, there’s something to be said for standing on others’ shoulders.

[xenus_dad]

Also curious if this is specifically about the visual design of the documentation or UX, usability, and ability to update in a low-effort manner. Not that those are exclusive, but curious if this is strictly about visual design.

[Olivier]

The main thing I was thinking about over lunch (besides visual refinement) was better consolidation and organization of resources, along the lines of what @tehn outlined in his post above. Something like central landing pages for Norns, TT, etc. could be great for easy reference.

EDIT - This, admittedly, doesn’t stray too far from what’s already there – maybe I am thinking mostly in visual terms after all

[ppqq]

programming manual (something that is somewhere between the studies and API reference, with small examples… which could perhaps be integrated into the API reference possibly, though it could be tricky given the API reference is generated from source tags)

(my emphasis.)

actually, looking at ldoc, i see there are some smarts baked in to support inlining references to examples using a @see tag so this may not be so bad. (in any event we should see what’s actually supported.)

here’s a pointer to the relevant docs:

https://stevedonovan.github.io/ldoc/manual/doc.md.html#Examples

as for API doc styling, this bit provides a bit of context for how ldoc uses templates and css:

https://stevedonovan.github.io/ldoc/manual/doc.md.html#Generating_HTML

fwiw, the command we’re using to generate docs in the build is just this:

(cd lua; ldoc -c ../config.ld .)

playing w/ styling and templates should just be a matter of defining the right files (.lua and css respectively) and passing them along in the command line. if folks want any help integrating, feel free to ping me.

[glia]

https://monome.github.io/norns/

mildly off topic but i had not seen this (or lost the link if i ever had it)
thanks for linking here…the guides for scripting/api docs will DEFINITELY help me

i feel like i was too dumb to know i needed them and assumed they didnt exist yet in such an organized format

edit: perhaps it could be added as a bullet point under studies here

[tehn]

@glia: you hadn’t seen this site before because @ppqq literally just built it yesterday. but there is not necessarily a ton of new info-- it’s pulling from the github readme, and web-hosting docs that were previously only on the device itself (ie, norns.local/doc)

@xenus_dad maintainability is certainly what @ppqq helped improve massively with this move. since we’re using an existing code-documentation system (ldoc) we have a start, but general “usefulness” is something i’d like to put time into (and would love help) along the lines of what i mentioned above.

@Olivier yep the main monome docs page is similar to what you’re suggesting in some ways, but clearly the norns section needs more definition. but back to the original goal-- i’d love to see you css added to the teletype manual, and perhaps we can explore how to update the norns API css…

[Olivier]

Excellent - I should have time this weekend to establish more robust styles for TT docs (and the Norns API docs) and then submit them to you all for feedback. Is there a better place for me to share these mocks?

[ppqq]

Is there a better place for me to share these mocks?

the github issue @jlmitch5 linked above (norns#595) is an alternative but i think here may get the most eyes.

wherever is easiest for you.

exciting!

[jlmitch5]

@Olivier these mockups are awesome!

I believe I’d like to take a pass at modifying the pandoc template to confirm to these styles first. I believe I can get close from a visual perspective without too much trouble. I have a flight this eve I might try to knock this out on.

The biggest cons to the current build system are not so much it’s themeability, but more the toolchain setup, which is not super simple and has some tricky platform specific stuff.

[alanza]

For pandoc, part of the problem is LaTeX, it seems like, being a cumbersome beast with a crazy “setup cost” (multi-gigabyte distros, etc). It’s probably worth asking what we want from a PDF output of the Teletype manual vs. a webpage?

[jlmitch5]

Agreed on all points.

One big thing for me is being able to access the docs on my phone in case my laptop isn’t around when I’m working on a tt script

[rryy]

It isn’t suitable for the main documentation (I don’t think?), but maybe for the dust scripts, it may be worth looking at something like Locco. It’s a Lua version of Docco, which is a minimal, literate programming style documentation generator that generates HTML with the documentation alongside the syntax-highlighted code. While I haven’t used the Lua version, I’ve used some derivatives for other languages and found it easy to read, especially when browsing code (as opposed to reading a manual). If nothing else, the layout may be a nice layout inspiration.

[tylor]

Might be late for this, but here’s a great list of examples: https://github.com/PharkMillups/beautiful-docs Scroll down for articles about writing docs and documentation generators.

[jlmitch5]

thanks @dan_derks for the super fast modding and thanks everyone for the feedback! If you have more feedback specific to the teletype docs styling redesign (or latex/pandoc toolchain and building), please keep it in that other thread.

we can keep this thread more general in providing tools to create, examples and ux patterns of good web docs sites.

[tehn]

is there a PR lined up for this? it looks fantastic!

[jlmitch5]

@tehn Just local right now. My goal is to work on the proposed additional enhancements and fixes mentioned sometime this week and will open a pr sometime this upcoming weekend.

@alanza @scanner_darkly @sam do we have a concensus on what we want to do with the alphabetical ops section? It isn’t something I use personally (I go for the cheat sheet), so I’m not leaning one way or another. Just want to know what we want so I can work on it.

[scanner_darkly]

i think the discussion is still ongoing? would be great to hear from more people who use that section!