Organelle Wiki? Open source the official manual? Discuss

Organelle
1

If users aren’t aware @healthylives had planted the seeds of a user maintained wiki page for the Organelle.

(see this thread for how this started - New owner : instructions?! - #8 by thetechnobear)

And continuing the discussion from Mod Wheel Control?:

Ok, @oweno / @chrisk - I think you should update your online manual. :smiley:

The current version on the homepage is for v2.1 - is this in the process of being updated? I know for a fact from reading feedback on other forums (e.g. operator-1.com where I also frequent) that currently there is no “easy way in” for new users and I think that this could be addressed to an extent by collating a lot of the relevant information in a single place and would have thought a user maintained wiki would be the place for this to happen but I am a total noob at this sort of thing so correct me if I’m wrong!

Sorry this was going a little off topic so made a new thread for it.

2 Likes
2

I have taken it offline for now. Will await to hear community thoughts.

I had created sections for patching notes/tactics/howto, including integrating pedals, mod wheel, pitchbend, pagination approaches, and so on.

Also some notes on wifi setup and usage, the current state of OS 3, and some other resources, including an svg vector of the main organelle interface (for patch notes / documentation), and external links.

Finally I had begun a project to annotate the C&G youtube PD tutorials, as my learnign style benefits more from written notes than watching videos.

Thanks everyone!

1 Like
3

I dont think you need to take if offline, I think do think its a great idea

my only comment/concern was duplication of information, which in my experience tends to mean resources get outdated, and then can confuse people even more…

generally my thoughts are:

official C&G manual

I think the official manual here has a definite scope and goal , its somewhere for a new user to start… get themselves up and running, and I think it should cover everything that is in the Organelle Mother UI.

Im sure that C&G are planning to update it, but these things take time…
(and im partly to blame here, I dont have access to it, so when Im adding things to the OS , I cannot update it)

of course, its not practical for it to cover everything… and this is where i think a community wiki can shine
(e.g. pd programming specifics, troubleshooting things like wifi)

that said, Im sure @oweno and @chrisk would appreciate feedback on how the manual can be improved (rather than it some how being ‘superseded’

also one possibility is for the C&G manual to be ‘open sourced’, or put into wiki setup, such that the community can help improve/maintain it… in much the same way the OS is.
of course this is something @chrisk and @oweno have to decide :slight_smile:

community wiki

I repeat, I think its a great idea to have a community wiki, that can continue where the manual leaves off,
and perhaps collates information from the forum … which can sometimes become difficult to find in a historical sense.
the only thing ive noticed on similar products though is, the information can get ‘dated’ quite quickly, esp. if it goes into things like patch specifics.
… and sometimes ‘old information’ is worst than no information, because in the latter case usually just post the question on the forum , where other users are likely to reply with ‘current’ information.

I guess easy curation is the key, @healthylives is being really generous now by offering to curate it, but it might become a burden to keep it up to date long term… easier if any user can go update it, if they find something out of date?

anyway, just my personal thoughts… and i certainly recognise im probably not its ‘target audience’, though I could contribute.

1 Like
4

Thanks Mark!

I would love it if any user could update it. That was my thought in hosting it on github, though (pending the outcome of this larger discussion) I’d be happy to set it up on another platform that is more conducive to community contribution.

My perspective is as a mostly non-technical music hobbyist, new to PD, but comfortable with computers and the web, as well as design and education. I needed this kind of wiki as a learning tool and reference guide.

Another point, the idea for the wiki was prompted by a question regarding existing patch documentation, rather than patch creation or other usage questions. I think this is important.

It can be head-scratching to have a go at the latest brilliant patch without really knowing what button does what. And I totally understand that from a patch development standpoint, documentation is not the priority! Since I’m not a pd patcher, but I can sometimes get my head around these things, and like to organize information, my thought was to create some complementary patch documentation–again as an internal resource for myself, then potentially shared with others–so that I’d have a central reference for favorite complex patches, rather than having to hop around to patchstorage, old forum posts, the c&g factory patch list, etc.

5

yeah, I sympathise with that… its a tricky one, really the patch creator needs to provide something, and patchstorage does make the most sense, since we dont know if all users come to this forum regularly.
(I always cross post to here, but i still get questions directly on patchstorage about the patches - so it feels like they dont come here)

the issue again is also updating, say you had spent time writing up about one of my patches - then i release a version that changes it fundamentally, unless you happen to have downloaded/updated your version, you notes are going to be out of date!
(where as i, as patch creator, feel i have some kind of obligation on patchstorage to keep the description up to date)

as i say tricky, and part of the nature of Organelle being so open, and many patches i would say are experimental / exploratory… not an excuse, but I think influences the ecosystem.

back to wiki …

what we did for axoloti , was to use use discourse (this forum) as a wiki.

discourse allows for posts to be marked as ‘wiki posts’, these are different in that other users are allowed to edit them (trust level 3 and above iirc) … so we did was create a ‘user guide’ section, where we gathered these posts, so that the community had a way to help build the documentation.

now I will stay, it was of limited success…
we still have ‘complaints’ from new users about finding information, and the documentation is still not that extensive (and its a pretty technical product)
I don’t know if this was due to the technology, or just lack of interest in the community to invest time into documentation - I personally felt its was the later, one thing to ‘complain’ about something, another to actually do something about it :wink:

anyway, why we did this was simple… re-using discourse meant:

  • its was on the forum, so searches on the forum hit it
  • we didnt need to setup a wiki server, not worry about things like security/user admin

anyway, it might be an option to do here, its an easy option for C&G, probably just a new category to group the ‘articles’ , and perhaps bumping a few users trust level if they want to contribute.

discourse: more info on wiki posts, and what they are

6

Thanks for info on wiki posts, not something I knew about.

and thanks @ghostly606 and @healthylives for working on this!

The documentation since OS 3 is admittedly lacking. The original manual while a good starting point is not easy to edit, so it is hard to keep up to date with the OS updates… I’ve been thinking a wiki format for the manual might be better and allow us to keep it better up to date.

A community wiki is also a great idea. There are so many different ways to use the Organelle and gear that we don’t have or use in house, so users being able to add things like hook up guides, usb devices that work / don’t work, midi config, etc, would be hugely helpful.

I guess if both manual and community wiki are in wiki format, it would make the most sense to combine them. We could have access controls on certain pages, so for example the official C&G manual pages could not be edited. (@healthylives is this kind of thing possible with the github wiki?)

the other option is just fix the manual, and do wiki stuff on the forum. @thetechnobear are there options to organize these pages / posts and have something like table of contents? one thing I like about the wiki manuals that I’ve seen (usually MediaWiki or DokuWiki based) is clear organization of the information. Between C&G patch list, patch storage, C&G manual, and this forum there are already so many sources of information, I’d like to not make the problem worse!

2 Likes
7

Hey @oweno thanks for chiming in!

I actually love (really love) discourse so if hosting a wiki here would work, all the better.

Github’s wiki integration is OK–though I’m not sure about access levels. That being said I could already see it getting disorganized w/r/t sidebar navigation and organization, and yes, it’s yet another destination. Regarding UI and navigation, the organelle manual has a perfectly nice layout!

tldr I’ve love to see what discourse could do right here on the forum, but I’d worry about big picture navigation.

8

there are no special wiki features as such… (they are just normal posts, that others can edit)
that’s partly why we grouped them under a ‘user guide’ category, but you could put under some other title…
however there is a reasonable about of formatting possibilities within discourse, and so with some thought you produce something reasonable…
(e.g. you can link topics, so you could create a ‘chapter’ as a post, and then have a post that forms the index and links to it)

the issue is, whilst formatting in markdown is very quick, creating topics and linking is not as ‘automatic’ as it is in a proper wiki.

I played with the GitHub wiki in the past , and found similarly its was ok, but soon hit walls in a similar way - and you need to be a collaborator on the repo to be able to edit it.
(its a while ago i played with this, so its possible its been improved)

if you have a server, you could setup a wiki server, for sure this is better, but then you need to consider how you authorise users… perhaps these days it might be possible to authorise thru discourse i.e. so forums users are able to update.
(this is all important, otherwise your wiki will be attacked :frowning: )

I agree, fragmented information is a problem, i think its pretty important its clear to end users, how they use each source…
i don’t think its too bad now:

  • organelle.io is official C&G info/patches/updates
  • patchstorage is for 3rd party patches
  • forum is Q/A

and i guess youtube too :slight_smile:

I’m pretty comfortable searching different resources, but Ive see hear and elsewhere, that some users do prefer a more structured approach … but that implies ‘curation’.
of course, wiki is just one curation possibility, but there are others - i wonder if someone did a blog, or even a video blog… which covered tips, patch reviews , it might also do quite well.
frankly , people seem to enjoy videos more than reading manuals - again i know not true for some.