Crow & end-user documentation

regarding the general question of how to target user docs, a while back i saw a presentation by anita sarma about gender-inclusiveness in software developer tools (my wheelhouse) that was fascinating and i think very relevant here. what i took away was how there are a number of distinctly different (and possibly largely disjunct) ways to learn and approach new tools. the talk was largely around the clustering that occurs around gender but there are also strong clusters around other things (native language, socio-economics, etc). the rub for me was that i saw our approach to documentation in a wholly new way. we had fully embraced a kind of “inteprid, tech-comfortable, coding adventurer” persona who is comfortable learning as they go but this in fact came at the expense of folks who were naturally more risk adverse and would prefer a more linear, show-me-your-cards and up-front narrative.

the take-away for me (and what is i think coming up here) is that a well-documented thing might actually benefit from multiple documentation arcs that correspond to the different personas (for lack of a better word). the super good news here is that we have an amazing community here with a lot of successes already. (who hasn’t learned infinitely from @okyeron’s excellent i2c write-up, @scanner_darkly’s generous TT work, @dan_derks’s tireless attention to detail, @zebra’s deep-dives, @tehn’s patient explanations, etc? and obviously the list goes on!)

so yeah, onward! crow is an amazing thing. i’ve been lucky enough to play with one and can testify that it fulfills it’s promise and is really not at all like anything else. it’s open-endedness presents some real challenges to documentation for sure, but together we’ll get there and we’re off to an awesome start already no?

cheers all! :beers:

looking through sarma’s publications, i’d say Gender-Inclusiveness Personas vs. Stereotyping: Can We Have it Both Ways? is the most directly relevant to the talk i saw but really there’s so much of sarma’s work that is on point; ping me if you want to chat!


while i think i agree with where you’re going, one thing this implies isn’t quite right. that is, i don’t believe crow was designed intentionally to exclude any members of the community. my sense is that @Trent and @tehn (and needless to say @zebra) care deeply about inclusivity but maybe at times sit too close to the metal to see things through a novice’s lens. that said, in my experience, they are hugely embracing of improvements to docs and UX that improve things. that’s where we fit in and how this works more as a collaboration and community effort.

aside (and i hope not flame-baiting): my take is that crow, like all things in this ecosystem, is very much a work in progress. it was a long time in coming and won’t be fully baked until we make it so. this approach to releases is pretty interesting and IMO extremely inclusive. by putting things out in the world before they’re totally done @tehn and co are essentially inviting us all into a process of design and iteration. cool, huh? that said, totally not for everyone. what surprises me about this thread is that folks haven’t embraced this cost of doing business more. buying a first-run crow is very different than buying a Disting. to be perfectly honest, i think it will be a while before crow totally stabilizes but then i think that comes with the territory and the upside, that we all get to help steer it to be the thing we all imagine we want is worth it. i wouldn’t be here if i didn’t!


Thank you for calling this out. I was did not intend to imply (and I am sorry if anyone inferred) that there was an intentional exclusion. But in the enthusiasm (and it is warranted - this is an amazing accomplishment) to get this into the hands of capable users, less capable ones are left behind. Which is not the end of the world (see below).

As I said much more eloquently 2 days ago:

… so I’ll just leave it there. We’ll get there. And it’s important for me to add that above all, I trust @trent and @tehn and @zebra and @alanza and @dan_derks and any number of you bright, lovely people to reach back and offer the rest of us a hand-up. It’s the Lines way to take care of each other.

All that said I’m glad I raised my hand and spoke up. Having done so, I’m happy to sit down.


I know I would be!!! Your ER301 videos were essential in my grasping that module :pray::pray::pray::pray::pray::pray::pray::muscle:


7 posts were merged into an existing topic: Github Basics

Just want to publicly say thanks to everyone on this forum that has ever helped me out with any of the various questions I have asked on a wide range of topics. I have asked for much here and have never gone without a reply; a generosity received that is not equal to that which I have put in.

Also want to express my experience where any time I feel there was a gap in my understanding of how something or another worked due to a lack of documentation that was meaningful/helpful to my specific way of learning AND where I was hesitant to ask publicly (etc) for whatever reason, it was only a matter of time until a resource magically appeared. My fav example is the JF technical map. Had been scratching my head at doing anything beyond the most surface usage of the module and then one day that just showed up. There is a collective unconsciousness on the this forum that given enough time rises all of our understanding up.

Crow will be my first official monome product. I have maybe 10% knowledge of it’s potential and know full well my programming chops (very minimal) will be a bit of a mountain to climb. I saw “usb, 2 in, 4 out, 2hp, and scripts”. Normally, that wouldn’t be enough to purchase. But because I see Crows less as a ‘product’ and more of a ‘project from lines people’, I knew that I would purchase it immediately and that given time and the spirited contributions of the community I would be guaranteed to draw creative juice from it.

Fully stoked and I have no idea what I’m going to do with it.


i find that the more complex, engaged relationship with monome/manniquins is far more rewarding for me personally. i also have VERY limited time for music related things (maybe an hour a day if i am lucky) and have struggled with TT and /w and norns etc. but i think as a result of pushing through some of those frustrations (still plenty ongoing too) i have in the end made music i am proud of. music i would never have been able to create were it not for these devices and my adapting them to how i think/work.



whether your interaction with a shop or service is online or in-person at a brick-and-mortar, NOBODY welcomes a customer who makes demands just because money has been exchanged

you brought up a decent point about improving documentation but have completely derailed your own argument with extreme agression and unreasonableness (for what reason i don’t know)

i’ve lost count how many features monome have improved on or added to their software/hardware because fans discussed it online & asked politely

we all benefit from that


could have fooled me! :stuck_out_tongue:
i’m right there too… hour a day TOPS unless I want to sacrifice sleep by staying up into the wee hours.

I also to be clear if i wasn’t before, I’m not complaining about the difficulty of figuring this stuff out, but if we’re discussing the documentation I feel compelled to voice my feelings on the matter and directly contrasting @alanza’s comments about how good the studies are, as someone still trying to figure it out, as opposed to someone who is proficient. I have conceded that my life doesn’t currently allow me the time to really dive in and spend the time that learning it all requires. But I also do feel that, and as mentioned, it could very well be my learning style, the current studies don’t necessarily work for well for me. I feel that a video just sort of explaining some of the concepts and terms etc could really unlock some of the concepts for me. The Ansible manual was a bit confusing, but after some of the videos… can’t remember who’s… I figured it all out fairly quickly and can use the manual to look up specific features, options, etc rather easily.

And to reiterate I really appreciate all the hard work of the people that DO spend their time programming, and sharing and helping those of us with less time, knowledge, inclination to program and develop for Norns, TT, etc. I think that is what draws me to the Monome world is the ecosystem that allows me to find uses for these devices in my music making without having to learn the programming.


Hi all. My apologies for coming off as condescending earlier. I did genuinely mean the “learning is hard” comment. I found @nutritionalzero’s comments incredibly frustrating.

I do think the Teletype studies are actually great, but I’m happy to be wrong about that. I think that there is a big gap between being able to read the studies and being able to consult the manual and learn from it.


just to speak quickly to the idea that crow is unfinished or beta/etc…

we ensured the crow would work perfectly well out right away as a norns CV interface or ableton CV interface— because this was the initial use case that caused crow’s existence. the lua environment was a breakthrough to become another thing— the part that requires all of the tutorials and learning because it’s a little weird, i admit.

but it’s also the bit that’s going to be somewhat fragile in the sense that i know everyone here will try to push this thing to its limits, and that’s a great thing— to figure out what this device can do. and there are dedicated people here interested in that group exploration, which i am very excited about.

but the norns CV and ableton devices will deliver. they are not complex, and they give immediate musical powerups to other tools— and i suspect these will be what i use myself most!

thank you for all of the suggestions above— we’re working on it


Bringing this around to crow’s documentation again - I just spent some time poking around trying to find an answer to how crow handles leader/follower (is it automatic or configurable?).

This is not mentioned at all on the product page or “technical” docs. i2c is mentioned in most detail on the main github repo readme - unfortunately this is not significantly linked as a source of help/documention from the “docs” on the monome site.

I would strongly suggest adding a more “detailed information is available on github” link rather than just “you can follow development on github”


I meant no insult or trouble by that comment earlier. I’m sure that it’s in release condition!

I was trying to use a analogy rather than a direct reference. I could have used some better language, not thinking through that someone might take me literally. I hope that I have not caused any confusion.


thanks for calling this out, steven – I’ve captured the answer to your question in the FAQ. [fwiw, the FAQ is a bucket to hold answers without definitive homes yet]

this weekend will be a really solid test for what information needs to live where and I super appreciate the steady feedback to help curate.

I’d actually really like to see the main crow readme get trimmed down to details and links to further documentation – the massive scroll is definitely a lot to swallow and some of the info needs culling. that technical page could house a third + all that scripting info should live here.

1 Like

I just want to say, the blank canvas concept that monome has always been about, is exactly what excites me and draws me to them. I remember the first week I spent in my studio with the Teletype. I made almost no sounds. Just sat there in silence typing into my modular. Ha! But eventually, it became the heart of my modular system.

It’s not for everyone but for those who can appreciate it, it’s super rewarding. I’m pumped for Crow now. At first I thought it was mainly just for Norns owners but the fact that you can design its functionality and upload it to run standalone is huge! And in 2hp! I’m eventually gonna need more than one. I’ve always had trouble with programming languages but this seems like the perfect motivator to learn.

I’d say, If you bought one and don’t want dive into all language business, put it in a box and save it for six months. Don’t sell it. It’s going to be worth it when all those user created scripts accumulate and all you have to do is upload and go.

Bravo Monome! Amazing design once again and looks sick, as usual!


Yeah I get the feeling that once a library of things exist for crow it could become an alternative to a Disting in some respects


going thru the docs and am noticing a similar blindspot that was encountered briefly at norns launch…maiden/matron/supercollider/lua/dust/tape all made reference to specific things and the framework became easier to grasp once explained but, initially i think i was confused by how the puzzle fit together

is there any benefit to defining certain terms? for example now we have “scripts” being used to describe basically the same concept within norns, tt, and crow ecosystem but each type of script is very different (and non monome users might be expecting the word “application”)

that’s merely an example

what’s actually stumping right now is the relationship between crow/druid/python/ALS and lua…i cannot parse out the exact relationship based on the docs so if someone approached them with little background knowledge of these devices they might also be confused

as far i can tell, whether you write individual strings of text or full standalone scripts for crow, the editor is druid and the language is technically lua but asl is a proprietary set of commands which functions within druid and follows lua syntax…correct?

any thoughts on how to translate this and document it clearly for others?

edit: some of these questions are answered in the readme on gh…hold on


excellent thoughts, thank you!

pushed some changes to the FAQ to reflect these bits. does that feel right?


I think this is perfect
thanks Dan

hopefully others find it helpful too!


Thanks so much for this—definitely making it easier to understand.