Norns technical discussions on lines (& moderation)

anon45924993 · 2018-07-12T02:55:31.519Z

Discourse has a plugin framework

Beginner's Guide to Creating Discourse Plugins - Part 1

Building a plugin in Discourse can be really simple, once you learn a couple of quirks. The goal of this post is to create a skeleton plugin and introduce you to the basics. Your development environment Make sure you have a development environment...

Reading time: 14 mins 🕑 Likes: 230 ❤

And a directory of plugins

Discourse Meta

plugin

Plugin directory. To post here, use the Request Access button on the group page. One topic per plugin please.

vehka · 2018-07-12T10:27:13.183Z

There’s a wiki plugin that converts a category into a set of HTML pages: https://blog.discourse.org/2016/05/using-discourse-as-a-community-powered-wiki/

TheTechnobear · 2018-07-12T10:33:38.137Z

a bit of my experience of documentation on axoloti, which is a kind of similar product to norns.
(at least in ‘challenges’), and also uses discourse (and GitHub, for both code and contributions)… its been running for 3 years now(?) so is mature, and i think has a pretty vibrant community…

so when we first created the axoloti discourse forum, I seeded the forum with a user guide, and install instructions all created in category (called user guide), using wiki posts.
it took me a while, and im not a technical writer, just a developer, so the hope was others would expand an improve on it.

some thoughts on this:

discourse only allows the first post to be a wiki entry.

this actually is quite nice, you can actually allow comments to be about improving the doc, or close it, but this still allows editing.

the markup is ‘ok’

i thought fine for my needs, but many kept saying it would be better in a proper wiki (linking is the main thing, but i also often users lack of familiarity with the finer points markdown)
its advantage is quick and easy (for me), and it sits nicely alongside other posts for searching, and its easy to link to… but its has it limitations.
(as @vehka has just posted, we also export it to html (or pdf?) so it can be delivered with the software as offline documentation)

non-collaborative

a technical issue, is there is no multi user locking/collaboration (at least last time i tried)
this means two users can edit, without any notification, and the the last ‘save’ wins.
really was only an issue initially, when i was adding new parts, and someone else decided to fix my typos

flagging content for adding

thats an interesting idea…
id say that one issue is lines (for norns) is kind of promoting a use model of discourse that its not designed for… discourse (and most forum) are designed such that new topics are put in new threads… and so tagging etc, is done at the topic level. and then are grouped by categories

whereas lines tried to put all norns topics into one topic (ok, several topics like scripting, but still coarse granularity)

so its creating a rod for its own back really
move to a development category with individual topics, then you can start using existing discourse features (as others monome products have?)
this also empower users to be more selective over the topics they wish to watch and not.

community documentation experience

I have to say im intrigued by any model that encourages community members to help the documentation effort.

that said, i suspect the ‘tech’ is unlikely to be the issue

this has been an area I’ve been hugely frustrated with on Axoloti…
whilst we had core documentation in place, of course new users wanted more, understandably. and they also were frustrated that this meant searching over the forum.
we agreed this was a problem, and ive been very vocal that the community needs to be part of the solution.

but countless times, Ive had new users turning up whinging, and saying if I help them get going, that they will document their process, and then contribute it… so i carried thru on this, gave them even more support than normal, and even said i would review what they put together.
sounds like a fair deal, good for everyone - no?

not one of them actually followed thru, sure they took the support and guidance, but didnt write a thing.

the results is , we have had only a couple of contributions to the documentation effort (which ive of course been hugely grateful for!)

but still we get the same complaints.
so unfortunately it appears, everyone wants documentation , but few are willing to put the effort in to create it.

so yeah, I feel a bit jaded/cynical about it now

important note: to balance this a bit…
i think the reason im frustrated about this, is because the rest of the ‘community’ features of axoloti works really well, we have lots of code/patch contributions, and lots of users that help each other on every aspect, and there are excellent discussions on broader topics like dsp.
so… its just this one aspect, that feels like it lets us down, and its the first encounter new users have.

so, if a different model , as @barnaby suggests works, it be awesome, and id look into following on axoloti…

documentation usage

from axoloti, id also say its apparent some people just dont read documentation, they will still want to post issues/discuss…
but at least if you have the documentation, you can just link them to it
(also as common issues arise, i try to update the relevant ‘doc’, again being in the same place as posts, makes this easier.)

however, i think alternative forms work really well…

the studies are a great way.
axoloti has tutorials, and help pages (like max), but they lack the explanations of the studies, and i think the studies are really nicely balanced in terms of size/length.
ive also done quite a lot of videos , which is now my preferred route
seems a split on users who prefer videos to docs, and vice versa.
(more on organelle, that axoloti in fairness, just because thats where my focus has been)

but also you have to consider the real issue…
e.g. do most users want a rPI how to guide, or would they prefer a download image.
(i did the former, as i didnt want to tread on norns toes, but i suspect most wanted the later!)

axoloti forum

if anyone is interested in what this all looks like you can see it here:
http://community.axoloti.com/c/user-guide,

also you might want to look at how axoloti discourse is structured…
of course, its different, as its doesn’t have the mixed focus of lines, but it does have the ‘development of code’ vs end-user split of norns.

one particular area that might be interesting, is how we organised ‘contributions’, basically giving each contributor there own thread - this seems to work quite nicely,
it gives each contributor a place to talk to ‘their’ users, and announce updates…
perhaps not the best way to organise it, but it has a nice feel to it

mzero · 2018-07-12T12:55:23.087Z

As a developer, I found that the interaction over norns and rPi here quickly became unfollowable if one wasn’t staying on top of it. I gave up.

It seems that much of the interaction in the various threads would have really be much better suited to a slack, or other form of live interaction. And the non-interactive useful bits were buried in the threads… and you needed to read them through to the end to find the caveats, corrections, and improvements.

In my experience with open source, forums like discourse are best after the core of the software structure and documentation has already been developed.

As for lines itself, I feel like to serve as a developer forum for norns would require a large number of finer tuned threads, and then those threads would dominate the board. Perhaps if they were in their own major category… but again, still feels to me like the wrong vehicle.

bobbcorr · 2018-07-12T13:31:18.878Z

mzero:

It seems that much of the interaction in the various threads would have really be much better suited to a slack, or other form of live interaction

The software development organization I’ve managed for the last 7 years has used the following:

A live text chat environment (with separate “rooms” for specific topics and projects) e.g., Gitter or Slack
A live voice chat environment (with screen sharing and notes tab) e.g., Google Hangouts
A durable wiki for preserving project documents with related narratives e.g., MediaWiki
A ticketing environment (with a vigorously-groomed backlog, release planning and assignments facility) e.g., GitHub or JIRA
A public forum facility (for accepting public feedback and discussing topics with users) e.g., Discourse, UserVoice
An executive-level project planning facility (for showing the ebb and flow of projects at the level of milestones), e.g., Trello

Software development is a team sport that suffers when roles become blurred. This is especially true of open source projects with large communities, something I’ve avoided managing because I value my health.

TheTechnobear · 2018-07-12T13:37:48.505Z

mzero:

As for lines itself, I feel like to serve as a developer forum for norns would require a large number of finer tuned threads, and then those threads would dominate the board. Perhaps if they were in their own major category… but again, still feels to me like the wrong vehicle.

yeah, I agree, lines its a bit split on its identity…
there are many that want it to be less ‘gear focused’ (see comment on hiding trade category),
yet its backed by a ‘gear manufacturer’, so its walking a difficult line.
(not only norns, aleph seemed similar, as also eurorack at times)
no solution or critique, just recognising its hard, and a balancing act the mods are doing a good job on.

mzero:

It seems that much of the interaction in the various threads would have really be much better suited to a slack, or other form of live interaction.

this may be true, though many of us are in different timezones, so not sure how ‘live’ it would be, but certainly the ‘transient’ nature of the discussions perhaps is better suited.

however…
Like some others, Im trying to reduce my social media consumption/footprint , and using yet more platforms - fills me with dread (actually, more likely i just wont signup, as I have to draw a line somewhere ).
this makes me wonder, perhaps this is a sub-conscious concern I have with GitHub issues for discussion.
whilst I use it as a repo server - I really don’t want to turn it into another social media platform.
(esp. now its microsoft owned)

but again, these concerns may be limited to me…
and there is an argument for the ‘best tool for the job’, rather than trying to arbitrarily limit social media platforms and forums i interact with.

tehn · 2018-07-12T14:00:35.152Z

apologies for my slow response. i’m traveling and internet access has been spotty.

one proposal:

use the (presently underutilized) Development Category which lines users are free to mute.

but i feel this is only effective if we avoid mega-threads.

unfortunately avoiding mega-threads is fundamentally impossible without heavy-handed moderation (because a huge percentage of users will not stay on topic and moderators will get sick of the extra volunteer work to be verbose at letting people know they’re off topic and their message was moved)

but, we can try this, but i’d almost caveat that if by posting in the Dev category we all make our best effort to stay organized and on-topic, and agree to be moderated (this may mean calling for more volunteer moderators).

it’s good also to remember that what we’re discussing here is effective means for collaboration, and i’m grateful that you all are sticking around to discuss the very idea of collaboration. thank you! i’m hoping we can figure something out quickly, so we can get back to programming, and then stop programming sometimes so we can all enjoy the musical utility of the stuff we’ve built together.

TheTechnobear · 2018-07-12T14:15:33.332Z

tehn:

but i feel this is only effective if we avoid mega-threads.

I think this is a ‘culture’ / by example thing…

here, creating new threads for specific technical things, or questions, has not been the way its done,
rather things get lumped into broader topics.
(because of lines broad nature)

if you start creating lots of specific threads, like
e.g. (Norns) how do I sync midi clock with norns.

then others will follow, as its seen as a norm

if anything on Axoloti we at times have the opposite issue,
where similar threads get created (as people dont search), so I sometimes combined (if its important)…
I less frequently have to split threads (but thats also pretty easy on discourse)

Ive generally never had too many comments about moving posts around (unlike closing),
people seem to view it as ‘tidying up’ - the only issue (which I think others have mentioned on lines) , is discourse doesn’t really inform the poster of the move very well - so Ive had people thinking its disappeared/been deleted (which they get uppty about … till you point them to it )

however, axoloti is a product specific forum, so ‘thread explosion’ is no issue
how well that works on lines - not sure…

do you think it been better to make development as ‘opt-in’ rather than ‘opt-out’?
then the new noise, might be less of an issue?

anon45924993 · 2018-07-12T14:34:58.278Z

Development has been part of monome culture since day one. Lines has expanded beyond that but I’d be sad to see it become a place where development is no longer seen as an inviting playground.

But I’d love to see more granular threads, more volunteer moderators (raises hand) and if the development category became opt-in, I’d definitely do that (but I hope we can make this action super easy to discover!)

Jonathan_Riley · 2018-07-12T15:01:26.292Z

Chipping in my two cents as a follower who is not deeply involved in development:

I really have enjoyed reading through the talk between active developers of the Norns platform. As someone not as well versed in these topics, I’ve found myself using these threads as a way of understanding 1) the development process, 2) the hardware side of things, 3) how these tie together. I’m fine with the discussion moving elsewhere (whatever works best for y’all’s ~process~), but I’m sure I’m not the only one who reads through all of the Norns threads top to bottom, even the development ones, and thoroughly enjoys it.

The developer category seems like a good idea. Hopefully it isn’t muted like the trade category, though.

anon45924993 · 2018-07-12T15:08:18.732Z

Jonathan_Riley:

The developer category seems like a good idea. Hopefully it isn’t muted like the trade category, though.

I think that is what might be what is meant by “opt-in” and it seems unnecessary to me as well.

Dogma · 2018-07-12T15:13:06.286Z

Ill offer another non dev perspective via an analogy - fun huh?

these threads in a general forum (meaning everything from obscure coding to high range ethical discussions - its the strength of this place IMO) are like a magic eye picture - if you see it right (ie your a dev and or right across the tech be it hardware/software ect), or your a musician (drummer say, like me) you might see nothing but noise. So any contributions from ideas from non techy people are difficult as its so splintered where would you put this info for it to be seen and relevant if you could nut your way to hopefully the right area

Also given Norns isnt even at release it makes it even more confusing to get a grasp of the whole ecosystem…

I dont have an answer to this problem

ppqq · 2018-07-12T15:20:54.829Z

Dogma:

these threads in a general forum (meaning everything from obscure coding to high range ethical discussions - its the strength of this place IMO) are like a magic eye picture

i love the analogy. i wonder if categories treated as lenses might not help here? (i admit i pay little attention to them myself but maybe with a little discipline they can be part of a partial answer?)

Dogma:

Also given Norns isnt even at release it makes it even more confusing to get a grasp of the whole ecosystem…

which is just to say, maybe it’s not important to be able to as long as there are ways to not lose the thread of the narratives you care about.

oscillateur · 2018-07-12T15:39:54.144Z

I’d prefer if there was a Norns category, which I could mute if needed (i.e. if it takes too much bandwidth for me) rather than using the Development category for Norns, as I’m really interested in all the Teletype dev threads for example.

sakul · 2018-07-12T15:42:37.703Z

You can mute the norns tag.

cmcavoy · 2018-07-12T15:53:38.267Z

If you need advice on how to maintain or contribute to an open source software project, Karl Fogel’s book “Producing OSS Software” is always a good source. He was part of the Subversion team for a long time, which was maintained by a company - but had a large volunteer contributor community. His advice is mostly geared towards much much larger projects, but it never hurts to page through it when you’re not sure what to try.

Here’s the chapter on forums, where he talks about what goes into the ticket tracker v. what goes into an open discussion forum.

Your mileage may vary.

vehka · 2018-07-12T16:10:01.316Z

Some forums have a culture of keeping the first post of a thread updated to reflect the contents of the thread, especially as related to newsworthy things. A hand-curated thread summary, if you will.

I feel that the Discourse feature of wikifying the first post is intended to support this kind of culture. If this policy was “enforced” a bit more here I feel it would go a long way towards solving the signal/noise issues that we have here.

scanner_darkly · 2018-07-12T16:28:37.891Z

could we relax the preference not to use tags for the development category specifically? we already have 2, norns and teletype. if we want to avoid mega threads it would help navigating multiple topics.

we could still limit it to mod curated tags only. i think something like toolchain, release discussion, feature request, issue, documentation, but could also be more device specific, norns on pi, for instance.

vehka:

Some forums have a culture of keeping the first post of a thread updated to reflect the contents of the thread, especially as related to newsworthy things. A hand-curated thread summary, if you will.

a good start would be for the OPs to turn their original post into a wiki so that others can keep it updated too (say, Ansible Earthsea topic is a good example that would benefit from it as it would give me the opportunity to update the first post with the link to the firmware/documentation).

TheTechnobear · 2018-07-12T17:36:33.737Z

scanner_darkly:

a good start would be for the OPs to turn their original post into a wiki so that others can keep it updated too (say, Ansible Earthsea topic is a good example that would benefit from it as it would give me the opportunity to update the first post with the link to the firmware/documentation).

yeah, just watch out for the wiki post multi-user issue I mentioned above… it can lead to a lot of confusion
(where your sure you updated something, but then come back and find its gone)
… its ok, for fairly static posts, but not if you have a few eager users updating it.

oscillateur:

I’d prefer if there was a Norns category, which I could mute if needed (i.e. if it takes too much bandwidth for me) rather than using the Development category for Norns

I think the proposal, is only for development related norns posts… other norns posts would remain in monome.

another possibility used on the C&G forum, is to use sub-categories , they are pretty good.
(esp. if you colour code their icons nicely)

vehka · 2018-07-12T17:55:45.665Z

TheTechnobear:

yeah, just watch out for the wiki post multi-user issue I mentioned above… it can lead to a lot of confusion
(where your sure you updated something, but then come back and find its gone)
… its ok, for fairly static posts, but not if you have a few eager users updating it.

Yeah, it would be best if new topics were always started with the implied responsibility of the topic author to curate the original post. Under some special circumstances (original author gone/disinterested/etc) the post could be wikified. But, just to be clear, does Discourse lose the concurrent edits, or just save them as older versions, like most wikis do? If it’s the latter one, I don’t see it as a huge problem. If making a longer edit, just put a notice up top or something.