Crow & end-user documentation

(staff notice: to keep the here: crow release thread on topic, which is for general crow questions, the lengthy side discussion on “how should crow be documented?” has been moved to this thread.)

Crow has some “Software switchable pull-ups” according to the documentation https://github.com/monome/crow/blob/master/README.md#pullups and
Here: crow

Is something like this an okay start? Most of the details are punted to the lines thread.

1 Like

Sorry, should have linked the full PR here, which would add that link to the monome.org/docs/crow page and others. This Github repository (https://github.com/monome/docs/) is used for community contributions to the monome.org docs, so if this PR is accepted these changes would show up on monome.org shortly thereafter.

3 Likes

I think this PR and the i2c thread are both useful references, but maybe there should also be a quick start guide in the crow docs for someone who just wants to figure out how to hook up crow to turn Just Friends into a poly synth, for example.

Something along the lines of “here’s the bare minimum you need for this specific setup and here’s how you connect it” might help demystify it and make it feel a little less intimidating for the “layman.”

7 Likes

you are speaking my language! a thousands times yes.

5 Likes

I get that the top post is a little long, but I was pretty sure explaining i2c to people was a solved problem?

2 Likes

since we’re shipping today (eeee!!) I want to ensure that we don’t lose any opportunities to polish the docs before folks rely on 'em.

would these bits of info be helpful?:

  • the minimum requirements for crow to interface with your system in a few use cases (to do x, you need y)
  • a few examples of possible configs? “if you have [specific devices], you will want to connect them like this”
  • “if you have [specific devices] connected to crow, you need to enable pull-ups. otherwise, you do not. for more info about pull-ups please visit these docs/thread.”

also, watching these convos the last few days, I’d like to open up a few new threads:

  • crow help: norns
  • crow help: druid
  • crow help: max + m4l
  • crow help: general (connectivity, device q’s, ecosystem)

a. do those doc additions feel relevant?
b. would it feel good to have these threads available + does it feel like that would help avoid pileups?


this is a little more complex, because approach will change depending on your context and will constantly evolve as members of the community create new entry points. for example, if someone is not interested in coding anything (including live-coding) and received a crow today:

  • norns: awake is the only current script that speaks to Just Friends (though this will definitely change as folks receive crows)
  • max (even an expired trial): the [crow] help patcher has a dedicated tab for i2c which has a Just Friends poly patch ready to go
  • m4l: ^^jf_synth on a Live MIDI track

here too, I’d say that a lot of great conversation will likely crop up in the threads to address this need in a meaningful way. I bet we’ll get some fantastic standalone scripts shared so that people can just pick and choose their crow’s functionality.

hope this helps further the convo, at least?

14 Likes

This in particular I think would be very helpful. Thanks for writing this up!

3 Likes

It is, but it’s also heavily centered around writing code and loading code, whether running on a computer, the device itself, or norns.

5 Likes

Arc, Grid, Norns, and I expect Crow, all rely on people writing code to make them musically useful.

15 Likes

Seconded. In the wide world of electronic music making devices, I’m using monome stuff (and Norns in particular) in large part because it isn’t defined for me. I like the ‘figuring it out’, the community engagement as support, and the bloom of ideas after a ‘new thing’. I have other devices if I want to open box > press a button > make a sound.

9 Likes

Does it have to be like a secret society though? Can’t you have your fun while there are some kind of useful templates and examples for people who do not want or have time to “figure it out”?
Is it intentional to be “cryptic”?

4 Likes

I’m sure there will plenty of help via this forum. Things will probably develop in a way similar to Norns, where over time there will be more scripts and examples to draw from.

6 Likes

I think these would be helpful additions to the docs and is exactly what I had in mind.

I have a good idea of how I want to use my crow, but I can see how it might be confusing to someone who just reads the product page and doesn’t spend a lot of time on this forum. I also recognize it’s probably challenging to write comprehensive documentation for devices that are open-ended and support so many different use cases.

Anyway, I’m excited to get mine and dive in!

6 Likes

These would be super helpful. I’m actually not 100% clear on how I’ll use crow when it arrives, but I’m sure it’ll find it’s niche. My setup today (not that I’m asking you to cater any docs to my specific system but just throwing out a use case):

  • No norns as of yet
  • Teletype (leader, always)
  • ER-301 (follower, always)
  • 16n (follower, always)
  • TXo (follower, always)
  • TXi (follower, always)
  • Ansible (usually follower, occasionally leader, and when it is I either don’t use Teletype i2c, or do so knowing that I could possibly lock a module up drop messages)
  • crow (tbd :slight_smile: )

These are all currently all on one bus via Teletype backpack.

2 Likes

The crow and norns “markets” are both classic “early adopter” communities right now. They are very comfortable with coding, they are adept at integrating different tools with a minimum of hand-holding, and they are very patient with gaps in the product.

What I’m hearing in the last dozen or so posts is a request to adapt the communications about this module (and perhaps the larger ecosystem) for a less code-friendly “early majority” community that is less adept at coding, requires (or at least appreciates) more hand-holding, and is more focused on using the product as opposed to tuning/developing the product.

These two communities require very different sorts of documentation and guidance in order to make use of products. When the time comes to help shape the documentation for the latter, I offer myself as tribute to help in the process, as this is what I’ve done professionally for (checks calendar) almost 30 years.

For now I think the enthusiasm for the solution is very high, and that’s drawing out both communities, only one of which feels confident with the prospects of using it on Day 1. I would encourage some patience. We’ll get there, together.

39 Likes

I fall into the second group. Not a coder, not a builder, just a long time synth user and generally self-taught enthusiast…

I find the recent reorganization of the Ansible docs to be a huge improvement, and look forward to seeing similar approaches adopted to other devices, if possible…

6 Likes

Bit of a deviation from the current discussions, but sad I missed the “initial dispatch capacity” this week but excited for the next one. Now I have to figure out where to fit it into my current setup :smile:

On the current discussion, I think I fall pretty firmly into the first bucket but with caveats. I’ve been a professional engineer for over a dozen years, and I both simultaneously love the programmability of crow, but also slightly mourn the loss of physically that doesn’t involve a keyboard. However, I’m incredibly excited how this is going to integrate into my current workflow and modular, which is still very heavily focused around the wiggling of knobs and teasing out of sweet-spots.

Also, being very new to Lines and this community as a whole, the level of discussion and collaboration here is staggering and very unique and special.

6 Likes

I have a slightly different take on this, speaking from the perspective of yet another person who has a lot of experience in the product management realm.

I think we may be mistakenly conflating the standard ideas around how products or ideas graduate from one market to another and how communication works in those spaces with what these products are fundamentally trying to do (both in a practical and larger sense).

everything monome has done for its entire existence has been about not providing upfront rigid structures and also not about explicitly seeking standard business growth (which is what drives the perceived importance of satisfying ‘early majority’ users).

crow seems to be perfectly in line with past products from monome (I’d even venture that is has more connective tissue and existing functionality at launch than many previous tools). the nature of a headless open-ended scripting machine is that it’s going to be pretty opaque and even recognizing that, I actually think I get crow more at launch than I did norns.

if the goal of these products is to explicitly avoid saying what they’re good for while making them open to inviting anyone interested in defining that value for themselves and sharing the results, then that is going to defy much of the common wisdom about how to communicate about functional products.


all that said, as someone who…

  1. wants to learn lua but hasn’t yet
  2. has a Just Friends but has never used the polysynth functionality
  3. knows a tiny bit of Max

…I’d love a basic primer for physical connections and software I need so that, if I do buy crow, I have some sense of what I’ll need to make it go without going on further scavenger hunts for forum posts and obscure cables.

I think the main hurdle is not 'what is crow?’, but ‘how do I get started with crow’? I think it’s perfectly possible to lower the threshold for the basics of what you’ll need to connect crow to other stuff to send voltages and make sounds without having to dramatically change the communication model. everything @dan_derks suggested above seems perfectly sensible to me.

I also suspect that, as the community grows what crow is, that initial list of stuff will fairly quickly fail to accurately describe all the things you can do with it.

19 Likes

This is critically important for those of us who are not coders or engineers.

I understand that the thrill of designing and coding and modifying code and hardware is a deeply compelling universe of its own, and cannot criticize the awesome folks who go spelunking in those rabbit holes…

But the rest of us, who lack those skills or inclinations, really do need hand-holding, or perhaps product ambassadors, to render these wonderful developments actually usable…

Otherwise we’re left with rather expensive mystery devices that are almost impossible to make sense of…

It’s one thing to learn how to even use Ansible Kria, but it’s another level of mountainous learning curve to learn Lua, Max, supercollider, II, whatever TT is coded in, and more (what am I missing?)

I don’t expect those with the mad skills to stop and wait for the rest to catch up, that would be unfair to them… But to the extent that those with skills are willing to contribute to less oblique learning pathways, I believe the community as a whole benefits…

Not intended as a rant btw, just a small plea for continued development of learning tools appropriate for real newcomers…

As mentioned earlier today, I’m really appreciating the way the Ansible docs got restructured to be more digestible, many thanks for that!

4 Likes