Docs: now more open

As I have mentioned elsewhere I lack the technical skills and knowledge to build this stuff, but I have much interest and enthusiasm to work with a team, if that kind of approach makes sense…

1 Like

pretty much same re: technical skills. hence my offer of gathering info. i was hoping you’d volunteer tho b/c i think your background makes you especially suited to organizing/framing things in a way that makes sense, and your absolute passion re: this would be welcome.

1 Like

go forth and populate this: Index: lines resources

3 Likes

Oh, I definitely am volunteering!

I was just pondering the possibility of teams for different aspects of the ecosystem, an example of which might be a Crow team, since I just got my Crow and have been trying to make progress on learning it with some very kind help from a few of the Jedi knights …

The Crow team could manage a Crow wiki (or Crow section of a larger wiki), -collecting links to threads or even better, extracting and refining info from threads, -receiving alerts from members about useful posts, outside resources, etc, and curating such resources in a manner that makes sense to the team with input from the members and the “management” who are also members but have certain perspectives that should be respected…

There’s collaboration and yet still a degree of freedom…

It sounds fun to me!

1 Like

Teams would be a good way to do this. Another might be a one or two week sprint on a particular topic?

3 Likes

Happy to contribute visual designs and related ideas if that’s helpful! Had a ton of fun re-working the Teletype web manual, and that structure could maybe be a good jumping off point…

3 Likes

Here’s a rough proof-of-concept for a side nav layout:

https://monome-docs-nav.glitch.me

Don’t pay too close attention to the actual nav elements – just threw these in for quick demonstration purposes.

I’m thinking that a structure like this could lend itself well to different forms of documentation (like the norns and crow studies, for instance):

Looking forward to hearing your thoughts/feedback/ideas!

4 Likes

I like the layout. I would encourage anyone working on this to be mindful of mobile screen sizes. I tend to browse these sorts of things from my phone so I would appreciate it if it’s readable there as well.

2 Likes

Absolutely - it’s great to call attention to that now. My next step will be to explore some mobile-friendly versions of this concept and share here.

3 Likes

Yes was about to give you a heads up on the mobile version. A bit tough to navigate but I like the concept! Nice work :clap:

1 Like

Very nice!

Would this structure ultimately include links to external resources including things like instructional and artistic videos, or should those go on the new index on Lines?

1 Like

Would love to hear your thoughts. I collated a bunch of “high level” stuff in the nav, but even then it might be too overwhelming/granular. Curious if you have a specific structure in mind.

Probably worth a wider discussion! I suppose that as long as those resources have well-tended homes outside of monome.org, it would be easy to at least link out to them from somewhere in the help pages…

Definitely worth further pondering…

There is some unavoidable overlap between the index and the monome docs, so sorting out what the primary home of various information should be presents some interesting opportunities… I’m aware that we don’t want to create needless redundancy, but the ability to hyperlink allows for some helpful cross referencing…

Thanks for all your great efforts on these issues!

So I think maybe for mobile having the navigation window on the side disappear after you choose a section to look at? Here is how it looks on chrome mobile so you have an idea.

2 Likes

@Olivier this is beautiful!

we’ve already started some discussion on github: https://github.com/monome/docs/issues/163

@Oootini is exploring some jekyll search options.

seems you have the styling and layout well in hand.


to clarify— this discussion is about the MONOME docs. we are attempting to make it more organized (sidebar) and searchable. i do not expect the actual content of the docs to change greatly. things will be moved around, and expanded, but i’m not about to turn the monome docs into a general learning center— that’s what the Index: lines resources is for!

8 Likes

Roger that! Thanks. I’m actually thinking of a sticky, collapsible nav for mobile that would sit above the content. Just need to mock that up.

4 Likes

my partner is a new-ish norns shield user and was going over the play documentation to learn the menu, but getting thrown off by the parts w/ stock norns assumptions, particularly the legend & getting the key + encoder numbers straightened out on the alt layout (aware most of this was all written pre-shield).

I have vector files for my case, happy to whip up a shield layout in the same style

3 Likes

thiiiis is great – it makes total sense that without a legend, you’d assume the leftmost key/encoder pair is 1. thank you for sharing this insight !!

excellent timing! we just had a “production meeting” the other day to plan out a total re-do of all the norns docs ahead of the shield restock. every bit helps, so if you can make a similar doc for shield, that’d be super rad :sparkles:

1 Like

progress report


norns docs rewritten

  • about two months ago, ahead of the new no-solder shield, we rewrote all of the norns docs to include shield at the start
  • we also revised the overall docs journey, hopefully making it easier for an uninitiated user to pick a topic and move linearly through toward better understanding that facet of the ecosystem:
  • we took the opportunity to clarify UI + hardware interactions with reference images:
  • we embraced samba as the primary method for file transfers between norns and another computer
    • sftp docs are still around, but it’s not a common usecase and so they’re hidden from the main learning journey

reference projects: help wanted!

inspired by experiences navigating references for our own personal learning projects (processing, p5.js, and [as always] supercollider), we’ve begun work on two different projects which we’d love help from anyone looking to kill some time:

~/~/~/~/~/~/~/~/~/~/~/~/~/~/
new: maiden REPL help
~/~/~/~/~/~/~/~/~/~/~/~/~/~/

with 210114, it’s possible to receive code hints directly in maiden by executing help() commands in the REPL:

example: help(grid)
--------------------------------------------------------------------------------
grid.connect( port )          create a grid table using device [port]
                                default [port] 1 if unspecified
                              (returns) grid table
.key( x, y, z )               function called with incoming grid key event
                                this should be redefined by the script
.led( x, y, level )           set LED at [x,y] to [level]
                                [level] range is 0..15
.all( level )                 set all grid LED to [level]
                                [level] range is 0..15
.refresh()                    update the grid LED state
--------------------------------------------------------------------------------
-- example
lx,ly,lz = 0,0,0
-- connect grid
g = grid.connect()
-- key function
g.key = function(x,y,z)
  print(x,y,z)
  lx = x
  ly = y
  lz = z*15
  draw_grid()
end
-- simple draw function
draw_grid()
  g.all(0)
  g.led(lx,ly,lz)
  g.refresh()
end
--------------------------------------------------------------------------------

help(grid) and help(clock) are pretty well fleshed-out, but there’s a ton of other modules which need documentation.

see brian’s changes for a great template for contributing to this effort

~/~/~/~/~/~/~/~/~/~/~/~/
new: command docs
~/~/~/~/~/~/~/~/~/~/~/~/

guiding principle: meatier than a quick reference and more direct than a study, reference docs give users who have gone through the studies but aren’t yet familiar with the ecosystem an actionable overview of the built-in modules.

provides illustrative + copy-paste’able code snippets to use in your own projects.

see the docs github for templates. if a module is preceded with lib. in the auto-gen api, then it goes in the lib folder :slight_smile:


have an idea for docs content? a whole new docs structure? please feel free to submit a PR to the docs github, or let us know here / help@monome.org :revolving_hearts:

14 Likes

holy crap multi-line strings !!! !!! i had no idea

i love how simple the implementation is, super easy to add to any script side library as well

1 Like