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.
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.
@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…
i’ve been talking with @ppqq about how to properly structure norns docs, as there are four levels:
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)
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.
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.
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.)
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: 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…
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?
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.
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?
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.