Web documentation design ideas and inspiration


#1

There is currently a github issue open to update the styling/layout of the norns API documentation to be more modern. @tehn also mentioned this could be an opportunity to give the teletype web docs a facelift.

I’d be happy to help out with the coding side of things, but I’m wondering if people have any web documentation they really like to use, think looks really cool, etc.

Also, if there are any designers who are interested in creating some mockups for these particular sites, that could be cool too.


#2

Would love to research a few things and even create some mockups! Especially interested in revamping the design of the TT docs…


#3

Yeah that’d be awesome! I think we should be able to share a lot of the styles between the two doc sites, because they share similar types of data, so if you want to target any mockups to the teletype docs, they would still be useful for Norns.


#4

Github Pages can be generated using Jekyll.
https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/

And this Jekyll theme might be a good starting point for implementing the design.
https://idratherbewriting.com/documentation-theme-jekyll/mydoc_supported_features.html


#5

@jlmitch5 - very rough mocks to at least visualize some basic ideas (parity w/ redesign of monome site, collapsible sections in the side menu, etc.). In the case of the TT docs, we might also take this opportunity to better group/organize certain things (like links to studies, reference PDFs, etc.) in order to make them more discoverable.

I’ll definitely spend some looking over the Jekyll resources that @jasonw22 mentioned…


#6

wow, this looks fantastic!

i can provide jekyll sources for the monome site if that helps?


#7

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


#8

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

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)

#9

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.


#10

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.


#11

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 :man_facepalming: – maybe I am thinking mostly in visual terms after all :laughing:


#12

(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.


#13

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


#14

@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…


#15

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?


#16

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! :beers:


#17

@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.


#18

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?


#19

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


#20

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.