MIDIbox documentation project

MIDIbox Documentation Project
1

Hi All

Lets all get together and write some good documentation for the MB. I see this as a massive undertakeing for one person (i.e. TK). It’s about time we gave something back. All MIDIboxers will gain from this. The MIOS platform has become so powerfull in the last year it has almost become unmanageable for anyone other than its creater to fully understand (I’ve been MIDIboxing for about 1.5 years now, and am still having serious problems).

I don’t know how we will organize this (any PROFESSIONAL technical writers out there?).

All the forum regulars have seen the same questions comming up again and again.

How about some kind of searchable Help file (you know, like all good software has). I think this would be great! When I started out building I would often have to go on-line to fine out some detail (I’m still iiving in the world of dial-up, so it is a hassel). I would have loved some kind of all-in-one solution that I could have downloaded with all the info required.

Like I say this is a MASSIVE job, but the MIDIbox is only going to get bigger and better so the sooner it starts the better.

I will not have time to co-ordinate such a project for the next six months as I’m writing my Thesis (the MB is a large part of it, and I will make this avalibe to anyone who is interested).

At this stage I can commit myself to documenting the generic remote set-up in Cubase SX.

Are you guys (Sorry if their are any females out there) up to such a project.

This project will be a living document as the MB never stays still.

What do you all think.

Regards

Rowan

2

Very nice idea. I think a WIKI might be a good way of getting this started.

3

I agree that a WIKI is the way to go.  I’ve edited a couple of entries at the Hammond WIKI site and it’s amazing how quickly a WIKI can build a documentation base.  It’s not very good for creating a printed guide but the ease of involving everyone in writing is outstanding.

First, of course, we need someone to host the WIKI and who knows how to administer it…

4

Sadly I cannot host a WIKI myself, but I know how to administrate WIKI. I was a administrator of Wikipedia (Germany) in the early days. So if anybody knows someone who could host, shout!

5

Isn’t it possible to host it at the midibox.org server? (I’m asking because you already have the password… ;-))

Best Regards, Thorsten.

6

What is WIKI? I only know “Wicki und die starken Männer” :slight_smile: - Can somebody post a link?

7

Hi,

I’m glad you guys like the idea.

Like Screaming_Rabbit I have no idea what a WIKI is. Could you direct us to a good WIKI so we can have a look at what you are talking about.

Does anyone know how the Linux community do their documentation?

Regards

Rowan  

8

Imho a straight-out wiki is a bad idea because by nature it is prone to irregular structure/formatting and generally impossible to re-organize.

I think it would be better to have a good division of labor. Something like:

  • one person in charge of nothing but the topical structure of the site
  • one person leading per project
  • one person per ‘topic’  (i.e., parts, their substitutions and dealers; boostrap/software loading and configuration, etc…)
  • someone to solicit help at the beginning and make sure roles are filled, and also to arrange for the one-off wriitng of articles like “all about encoders”, “how the din/dout work”
  • one person to check for broken links and fix them
  • one person to manage visual style
  • etc..etc..

It’s alot of positions but the idea should be to make the work load very light on everyone.. very specific tasks so that they can be done effectively

I do agree with the wiki sayers in that the content editing should be wiki-like, etc. but I fear a too-loose logical and visual structure if it all aspects were too open..

I’m not sure I should volunteer for anything technical since I havent finished my first MIOS project yet (seqr) but i managed a 30,000+ page / 250-name intranet for a global company and I’ve been making enterprise sites since '96 or so and could help out with an architecture.

Before I speak up and offer space, inquiring minds want to know how much traffic/bandwidth/diskspace midibox.org and ucapps.de soak up…?

9

Hi

great suggestions marr.

I’m not sure how others feel about your input, but it sound very good to me. The divison of labour is a must as it’s a huge job ahead of us. More input would be great because of your experience with such things.

The next and most important thing is what does TK want!

Regards

Rowan

10

I still think a WIKI is the way to go, especially in an open project.

A WIKI is a set of pages everyone can edit. So you can always correct mistakes, add more information, delete rubbish etc…

The biggest WIKI is Wikipedia : www.wikipedia.org

The thing about a WIKI is, it is not very time consuming for one person, because everybody works together and it is easier to participate. If someone drops out, it is no big loss for the project in total…

11

There is space on Midibox.org, and I have more on my other domains if needed.

I would like to try the WIKI, I’ll do my best to install a fresh WIKI over the weekend so we can play with it and make an educated decision.  If we don’t like it, no harm-no foul.  

I’m thinking even if we don’t like the formatting, it would be a good way to collect and organize the needed data to be formatted into whatever way is best.

Thoughts? Comments?

Have fun!

SmashTV

12

Basically we need a long term solution for “living documents” which can be created and modified easily by a group of volunteers. Currently we have two platforms for this: the forum and the MIDIbox portal.

To give you an expression, here an example for a forum based documentation:

(1) http://www.midibox.org/cgi-bin/yabb/YaBB.cgi?board=misc;action=display;num=1061917936

And here an example from the Portal:

(2) http://www.midibox.org/users/jim_henry/building_a_midibox_lcd_cable.pdf

Advantages of (1): low administration effort, searchable, very easy editable (not only by the original name, but also by the moderators), fast load time, possibility for other users to add interesting comments, questions and answers

Disadvantages of (1): limited formating capabilities, difficult to add pictures, not printer-friendly, no possibility to arrange the topics to a book structure

Advantages of (2): best formatting, very printer friendly, easy to add pictures/schematics/etc.

Disadvantages of (2): only editable by the document owner (in worst case only with a commercial system dependent software), impossible for others to integrate changes (e.g. due to new hardware), long load time, not searchable (only in the document itself)

I think that a mixture between a Wiki (which provides similar editing features like the forum) and a motivated maintenance as backbone (which arranges the topics, takes care for picture/schematic uploads, keeps the contributions up-to-date and not at least takes care for the system installation) could help to improve the documentation a lot.

As Marr mentioned it makes sense that many people take care for small tasks, otherwise it can take months for the launch, the        publication of new topics can take weeks and as a result the knowledge base will always be out of date. For myself it would be important that I’ve the possibility to change details very quickly, e.g. on software or hardware changes to avoid contradictions between the specs and the implementation.

Btw.: here’s a Wiki I’ve used some time ago and which I found very useful: http://alsa.opensrc.org/, but I fear that the MIDIbox Documentation requires a deeper tree structure (and therefore another Wiki software)

Before I speak up and offer space, inquiring minds want to know how much traffic/bandwidth/diskspace midibox.org and ucapps.de soak up…?

midibox.org: traffic ca. 11GB/month, 1000k hits, low bandwith (the webspace is very cheap), ca. 100 MB data

ucapps.de: traffic ca. 4GB/month, ca. 200k hits, high bandwith, ca. 70MB data

Best Regards, Thorsten.

13

If the plan was to produce a MIDIbox manual or something similar, we could do it somewhat like some open source software documentaion is sometimes produced, the documents could be produced and then editied by difrent people who had regestered themeslves to work on the doumentation.

All of the documentation could be kept on a CVS server and updated by people when changes needed to be made.  The advatage of this is there could be a release version upto date with the current version of mios and the hardware etc, but also the process of actuly updating the documetnts could go on behind the scenes, so we wouldnt end up in a situation with confusing half done documents.  Also the documentaion could be produced at the same time as people like Thorsten are hard at work producing new apps etc.

Anyway just my two-cents

ed

14

SmashTV: The format can be edited within a WIKI - just costs abit of work…

15

Why don’t you try before you decide :wink:

I have setup a wiki go and play. If you like it i can host it or you can install at ucapps or midibox.

If you don’t like it i can install another wich you can play with.

http://midibox.twin-x.com

login admin

pass midibox

I have no clue how it works. If you need help permissions on stuff gimme a PM

Have fun i hope this will start soon since i would like to participate!

16

I think this is the way to go… TikiWiki is really nice and easy to use…

17

looks good i recon

18

If you’d like to compare another Wiki documentation project, that evolved without any “bosses”, have a look at http://melbourne.wireless.org.au/wiki/?TheEvolvingFAQ

19

that looks good!

20

Wiki is up at the portal.

Have fun!   :wink:

SmashTV