Docs: now more open

Since that (excellent) suggestion would require modifying the discourse software and as a result might be a large challenge to implement and maintain, perhaps an alternative would be to have an account named something like @crowlibrarian and whenever someone finds a post that is especially useful for crow that person shares the post to @crowlibrarian. The person managing @crowlibrarian can then assemble and post the links wherever they’re supposed to go.

3 Likes

i think you can specify hashtags in discourse forums. for example, ##norns >> #norns

1 Like

Who would do the translation from a post to the docs?

Contributors interested in submitting pull requests to the docs repo I guess?

1 Like

I added two issues to the github repo, i think a basic search and nav would be beneficial. I’d like to help somehow :slight_smile:

I, of course, would never expect this so soon, but something perhaps to stew on for later: Crow seems to be just as complex as Teletype, and I’d argue that its relationship to other devices/systems makes it even more so. When I racked mine last weekend, I found myself with a lot of tabs open on my laptop trying to piece the story together.

I could see a future where crow gets the interactive manual treatment – a central place to collect the following: description/overview, version changes, update procedure, context info (m4l, norns, druid), syntax conventions, ii commands, etc. Basically a module-specific version of what @eblomquist is suggesting in Looking for collaborators on proposal for Index/Learning Center

EDIT: Totally forgot that @dan_derks suggested exactly this here!! 100% support!!!

3 Likes

Olivier,

Thanks for making this connection. It seems that the idea of making docs and other learning resources is in the air, and I’m thrilled to see it.

It would be fantastic to hear from @tehn and some of the other masters of the ecosystem as to their perspectives on these issues at a wholistic level, and specifically regarding some kind of centralized aggregation of a wide variety of resources with an eye to helping onboard newcomers…

Although I’ve been advocating this for a little while, I don’t want to come off as critical or arrogant… My advocacy is based on my own challenges in groking all the divergent knowledge systems and wishing for a way to organize the resources in a way that is as user friendly as possible…

My mother was trained as a research librarian, so this kind of thing is pretty deeply ingrained for me…

At any rate, I’m very happy to see these conversations taking place and I would love to be helpful in any way I can, recognizing my almost complete lack of skills in the tech end of this…

Thanks!

2 Likes

I use the Teletype manual and the reference sheet a lot. I’d love to see something like that too for Crow once things settle.

I’ve noticed as I’ve been going through the Crow docs is that they’re there, but I think I just need the main links to be listed as bullet points, rather than as a wiki style link in paragraphs of text. It’s easier to miss them as you skim.

3 Likes

Yeah, exactly. The content itself - it should be said - is gold.

2 Likes

it seems what we’re coming up against is information presentation. structure and visual layout.

i think it’d be good to migrate towards a sidebar navigation, and have a search.

definitely the content is there. finding it is tricky, because you have to basically internalize the whole thing before you know where things are. this obviously isn’t great.

hence a sidebar (“index” if you will) is a priority.

i’d like to say further— everything i’ve designed has had the goal of putting new knowledge and skills within reach of newcomers, and monome has been around for a very long time now and i’d have thought we’ve been generally succeeding at sharing knowledge as a community. so it’s good to hear feedback as to how to make things better.

that said, the monome docs cannot be a place for teaching everything— we cover some technical things that are sometimes required (ie, SFTP for norns, and now command-line folder navigation for druid)— but these are also very common tasks with numerous tutorials on the internet already. similarly, basic modular synthesis tutorials are served heavily in various places. and while these are all relevant to working with monome designs— they are fundamentally prerequisite knowledge. (that said, the norns studies attempt to make very few assumptions about existing knowledge, but re-reading them now, i see how there are certainly expectations of familiarity with certain tools and workflows).

my proposition:

  • improve docs navigation with a sidebar and search
  • continue to explore additional/new tutorial styles
  • start a lines wiki to collect resources: synthesis, programming, etc

since this community covers a lot of areas of interest, it makes sense to host an index of sorts here. the monome docs should (and will) remain specific to monome designs— though we will include links to external resources where relevant.

of course, the quality of an index will be determined by the maintainers and participants— so ideally there need to be a few strong volunteers to get such a thing started. anyone interested?

12 Likes

re: index, i would be very glad to help sift/sort/gather relevant content that’s extant on lines. i’ve been browsing a ton, and seeing a lot that would be helpful, including a bunch of intro synthesis/programming and other things that would serve to augment the monome docs (& help build that on-ramp).

a lot of those “prereqs” are definitely available in many other places online, if one wants/is able to navigate the signal/noise ratio. but i’m honestly more interested in pursuing research (etc) along those lines (ahem) with material that’s been vetted/suggested by lines members.

TL;DR: yes.

1 Like

I love this (place/people/solution)!

Thank you, thank you, thank you!

I feel so blessed to be here and so psyched for all the learning and creativity and community to come…

1 Like

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