One act gigging with this stuff is worth a dozen coders when it comes to legitimizing the platform. There's so much potential with what's here today that it blows my mind, but if it's "by geeks, for geeks" it really limits were

Yes, for deep technical discussions, the participants need to be qualified, but when one is blazing a new trail it's better to chop off the branch that's in your way than it is to let it smack the person behind you in the face because after all, they're an explorer too. ;)

Jack Bowling wrote: what I was tought is to never ever follow people on a trail too closely (i.e. I am responsible for my safety, not somebody else). [of

course, it's nice/good/appropriate to be considerate of people who are behind us]

not entirely sure how to translate it to software development:-) maybe don't use beta (pre-release, early release) when you're not ready for beta? erik

John Check wrote: not really, you will always have nothing, then something incomplete sort of usable and only after that there's something usable (if you're lucky:-)

developer could opt to not release unfinished stuff but then how would he get requirements? ... I don't remember a project (hobby or commercial) that would not go through major design changes. This is true for major project (with all the docs that osi 9000 (or whatever it is for software) requires) all the way to small (but non-trivial) scripts. It is a problem but I don't think there is a way out, it's kinda like there's no perpetuum mobile, you always loose some energy (=docs always lag, requirements change, bugs are found etc.) OTOH I guess now is a good time to focus on usability since the tools are on the verge of actually working (for general public, i.e. non programmers, non sysadmins) I just find it somewhat not entirely appropriate to make it sound as if developers were ignoring users/documentation/user-interface etc. That's the whole mindset that I see expressed fairly often, don't mean to accuse you of accusing developers, actually your email was quite reasonable (so I am, to some extent, using your email as a vehicle to rant a bit:-) erik

John Check wrote: oh, what I meant was: in each case, not always. In a sense that each project starts from nothing, goes through sort of something usable and hopefully gets to a stage when it is usable by (acceptable to) end-user.

and it seems like linux audio is getting there, i.e. it is not stagnating (that was my main point). And I agree that it is at the point where ease of use and documentation starts to be really important (which I think is your main point).

erik

I care Dammit! :) I think this is a valid point {& click). As a relative greeny to most things linux, I have found the vortex of info out there on some apps to be a show stopper many times. And then on ones that do have documentation...does it tell me the things need to actually know to make the software work? It seems that most that can write code or develop applications aim at an audience that should "understand where to look for a problem" and while that's all okey dokey, especially since they ARE doing it for free in most cases, it does not speak to attracting the masses to what has become a formidable adversary to MS in more ways than just server application! {at least that's what my ignorant perception of Linux was} The forums and wikis are good...they help a lot. And folks in general are just so very cool about helping. {quote: Jack_fst for e.g....not to mention dozens of other things I got help with here for other stuff) but they don't cover everything by a long shot. Sometimes I wont ask on here because humble is not my best suite! :) And I can't figure it out in many cases so It don't get to work! Who knows if that piece of software wouldn't have changed the world!!! :) Or at the least, it might have changed my world! And frankly many of these linux audio apps have done just that...rock my freakin' world at a great rate of knots! And I get out and gig at least a couple of times a month and get a LOT of interest over the PC stuff...I have the best seat in the house to push this out there...but we can make their journey easier today... {quote: "ah grasshopper, when you have crossed the rice paper without tearing it you will have learned" unquote} On Thu, 2004-08-12 at 06:13, Dave Phillips wrote:

When I started using Linux for audio a few years back (I started using it for other things in 1993) I found Ardour to be the main application that I wanted to use. Since I didn't think that I could spin up to help with the software in a short period of time I decided to help in another way - I wrote my own documentation on how to install it. I then started writing what little bit of user documentation that I could (later Paul asked that we all stop with the documentation). That was my first contribution to Linux Audio. More recently I've been working on JAMin and doing the install and user docs for that. I tend to agree with PJ (Groklaw) - documentation should be written by newbies because the authors are usually too close to the apps and are too familiar with them (it should be intuitively obvious to the most casual observer...). So, how about some of the users start in with documenting how they use the apps, what problems they had, or anything else that might help? If you've got anything to add to the JAMin docs (that I missed because it was intuitively obvious ;-) send it to me and I'll try to add it to the web pages. Jan

On Thu, 2004-08-12 at 09:58, Russell Hanaghan wrote:

On Thu, 2004-08-12 at 20:08, Russell Hanaghan wrote: Which, in many cases, is more important than what TO do ;-) Jan

On Thu, 2004-08-12 at 18:45, Russell Hanaghan wrote: Want to poll the group on this...I'm ready to start taking a stab at documenting this for others to use... My question is this...how useful will it be in the big scheme of things? I think Ive only read posts from like 2 or 3 other people that even wanted to do this. Most seem to be creating music or recording it. I do that to but not very much lately and thats not what this system is set up for. I would write it in the context of running on Mandrake as that is what I've experienced. Thoughts? Comments, input? R~

On Fri, 2004-08-13 at 10:28, Dave Phillips wrote: Well, seeing as you put it that way... 8~) Is there some specific format that works best...my intent at this point is to just do it as either an open office document or just plain ol' text file in Kwrite or similar. R~

Hi Russell: This is where I beg off. I know nothing about setting up a wiki, but I think there are a few people on this list who do know how it's done. I have no idea what your best choice for formatting might be, though of course plain text is understood everywhere. But like I said, I don't know where to begin with setting up wikis. Can someone on the list work with Russell on this project ?

>Is there some specific format that works best...my intent at this point >is to just do it as either an open office document or just plain ol' >text file in Kwrite or similar. >

IMO, you should do plain text, then mark it up. The best thing after doing the text version to hand it over to an SGML person, then it's trivial to generate other formats.

It's also easier to go text>wiki \>sgml>other formats than wiki>other formats

Wikis have their place.

> Go for it. Linux audio software development is already advanced, but >documentation is still at a fundamental stage. Regardless of how many >people use it, your docs may be the only additional literature on the >topic,

Is there some specific format that works best...my intent at this point is to just do it as either an open office document or just plain ol' text file in Kwrite or similar.

Oooops! Rocco needs a NAP! :) Fear not..._simple_ is mah middle name! Or is that my nature? :)

>Everyone has facilities to read plain text and html.

Don't forget... they may have to *locate*, *build* AND *configure* OpenOffice.org FIRST...

FWIW the HTML editing modes in emacs and vi are neat. Frankly I've considered HTML an extremely simple mark-up language to learn and use, and I've never needed to use anything other than vi (and the O'Reilly book on HTML).

Last Friday 13 August 2004 23:18, LinuxMedia was like: And OO.o creates appalling HTML. kword, incidentally is quite good at it ...

cheers tim hall

"Appalling" is relative. If you've ever been required to get some html exports from Powerpoint online, you'll have a whole new benchmark of appallingness  >8-O At least with OO.o you have some hope of getting something human-readable by feeding it through some cleanup scripts.

But I'm still looking for a good wysiwyg html+css design tool, and I wouldn't use OO.o for that. And no, bluefish doesn't do the trick for me either.

On Thu, 2004-08-12 at 18:45, Russell Hanaghan wrote: Want to poll the group on this...I'm ready to start taking a stab at documenting this for others to use... My question is this...how useful will it be in the big scheme of things? I think Ive only read posts from like 2 or 3 other people that even wanted to do this. Most seem to be creating music or recording it. I do that to but not very much lately and thats not what this system is set up for.

I would write it in the context of running on Mandrake as that is what I've experienced.

Thoughts? Comments, input? R~

I won't...thanks for the encouragement. I started with just that; a spare pc and experimenting. Now granted it is only as my PA fx right now but that is due only to lack of time and I can only experiment so much before I approach the boundaries of danger...IE; Not having the box up for the next gig!

Want to poll the group on this...I'm ready to start taking a stab at documenting this for others to use... My question is this...how useful will it be in the big scheme of things? I think Ive only read posts from like 2 or 3 other people that even wanted to do this. Most seem to be creating music or recording it. I do that to but not very much lately and thats not what this system is set up for. I would write it in the context of running on Mandrake as that is what I've experienced.

If you've got anything to add to the JAMin docs (that I missed because it was intuitively obvious ;-) send it to me

documentation should be written by newbies because the authors are usually too close to the apps and are too familiar with them (it should be intuitively obvious to the most casual observer...).  So, how about some of the users start in with documenting how they use the apps, what problems they had, or anything else that might help?

When I started using Linux for audio a few years back (I started using it for other things in 1993) I found Ardour to be the main application that I wanted to use. Since I didn't think that I could spin up to help with the software in a short period of time I decided to help in another way - I wrote my own documentation on how to install it. I then started writing what little bit of user documentation that I could (later Paul asked that we all stop with the documentation). That was my first contribution to Linux Audio. More recently I've been working on JAMin and doing the install and user docs for that. I tend to agree with PJ (Groklaw) - documentation should be written by newbies because the authors are usually too close to the apps and are too familiar with them (it should be intuitively obvious to the most casual observer...). So,

how about some of the users start in with documenting how they use the apps, what problems they had, or anything else that might help? If you've got anything to add to the JAMin docs (that I missed because it was intuitively obvious ;-) send it to me and I'll try to add it to the web pages. Jan On Thu, 2004-08-12 at 09:58, Russell Hanaghan wrote: > I care Dammit! :) > > I think this is a valid point {& click). > > As a relative greeny to most things linux, I have found the vortex of > info out there on some apps to be a show stopper many times. And then on > ones that do have documentation...does it tell me the things need to > actually know to make the software work? > > It seems that most that can write code or develop applications aim at an > audience that should "understand where to look for a problem" and while > that's all okey dokey, especially since they ARE doing it for free in > most cases, it does not speak to attracting the masses to what has > become a formidable adversary to MS in more ways than just server > application! {at least that's what my ignorant perception of Linux was} > > The forums and wikis are good...they help a lot. And folks in general > are just so very cool about helping. {quote: Jack_fst for e.g....not to > mention dozens of other things I got help with here for other stuff) but > they don't cover everything by a long shot. Sometimes I wont ask on here > because humble is not my best suite! :) And I can't figure it out in > many cases so It don't get to work! Who knows if that piece of software > wouldn't have changed the world!!! :) Or at the least, it might have > changed my world! And frankly many of these linux audio apps have done > just that...rock my freakin' world at a great rate of knots! And I get > out and gig at least a couple of times a month and get a LOT of interest > over the PC stuff...I have the best seat in the house to push this out > there...but we can make their journey easier today... > > {quote: "ah grasshopper, when you have crossed the rice paper without > tearing it you will have learned" unquote} > > On Thu, 2004-08-12 at 06:13, Dave Phillips wrote: > > Greetings: > > > > Recently I received a letter from a fellow who civilly noted how > > atrocious is so much of the documentation for Linux audio software. > > While that may be generally true it is also easy to point out specific > > excellent docos, e.g., Snd, Csound, LilyPond, Rosegarden, etc., though > > too at the same time it must be admitted that even those docs are not > > necessarily the most well-organized. Perhaps this fellow's most damning > > statement was made re: the HOWTOs available from the Linux > > Documentation Project (LDP). I decided to check out the situation > > myself, and here's what I found (the doc is followed by its last > > revision date): > > > > Linux Sound HOWTO July 2001 > > ALSA Sound mini-HOWTO November 1999 > > Linux MIDI HOWTO May 2002 > > Linux MP3 HOWTO December 2001 > > > > Worse, the LDP's own documentation refers back to these out-of-date > > pieces, making sure that readers continue to be misinformed. I mean no > > critique of the excellent LPD, but it seems to me that as a community > > we have an obligation to correct this situation. For all the talk about > > improving documentation, here's a chance for anyone to get directly > > involved. The format for these HOWTOs is simple and already laid out: > > what's needed is currency, someone to correct and update the basic > > sound & music oriented HOWTOs. Otherwise it might be better if we asked > > the LDP to remove the docs in order to mitigate confusion. > > > > Any comments ? Any takers ? Does anyone care ? > > > > Best regards, > > > > dp

Dave Phillips wrote: That is the state of most Linux documentation today, most of it is out dated, and anyone who has used Linux for a time will realize that anything older than 6 months *might* be wrong. It is easy to see where the problem is within the Linux audio developers community, it is the fact that most of the developers are coders as well as musicians, and thus have their proverbial plate full with two very time consuming pursuits, and have no time left to keep the documentation up to date. The fact that the development process is so fast just compounds the problem. The answer to the problem might be for the developers to have a book (an indepth manual if you will) published for them, once the application gets to a certian stage of maturity, that the public can buy. This would also provide a means for the developers to allow the application to be free, and still make a living. If a person doesn't wan't to buy the book they don't have to, they are perfectly free to sort through the online documentation. With other apps (cubase,protools,etc.) you have to buy the app and the book.

On Thu, 2004-08-12 at 17:50, Rick B wrote: What is needed is for non-coders who understand the apps to write the documentation, "power users" in the Windows-speak (I always hated the term). The developers are glad to help you if you have a question like "I am writing some docs for $FOO, why does it do $BAR, and what is the $BAZ menu for?". This is a great way for non-coders to contribute to open source.

The problem is there are a lot more people willing to write code for free than write user documentation for free. Many developers are not native English speakers, so in many cases it is much harder to write good English user docs than write code! Developer documentation is much easier because there is already a common language.

If you are a user willing to contribute documentation, the developers will bend over backwards to help you, because good user documentation equals fewer spurious bug reports and happier users.

Dave Phillips wrote: That is the state of most Linux documentation today, most of it is out dated, and anyone who has used Linux for a time will realize that anything older than 6 months *might* be wrong. It is easy to see where the problem is within the Linux audio developers community, it is the fact that most of the developers are coders as well as musicians, and thus have their proverbial plate full with two very time consuming pursuits, and have no time left to keep the documentation up to date.

The fact that the development process is so fast just compounds the problem. The answer to the problem might be for the developers to have a book (an indepth manual if you will) published for them, once the application gets to a certian stage of maturity, that the public can buy.

This would also provide a means for the developers to allow the application to be free, and still make a living. If a person doesn't wan't to buy the

book they don't have to, they are perfectly free to sort through the online documentation. With other apps (cubase,protools,etc.) you have to buy the app and the book.

Rick B

On Fri, 2004-08-13 at 22:39, John Check wrote: <snip> I'm not sure it's possible to attract testing effort _without_ sidetracking those people - it's somewhat of a necessity given the (often alpha) nature of the development. You need a certain sort of person to deal with frustration and testing - preferably one who has an axe to grind :)

Some time ago I offered my services (months of cvs up; ./configure; make; make install every night) to a project in the knowledge that it would consume all of my spare time for a few months - and I did so for two reasons; 1. due to an accident I had rather a lot of time to spare, and wanted to make something useful from that time 2. i believed in the goals of that project and wanted to help it reach those goals (so I could actually use it - [see, selfish really]).

Perhaps others can offer alternative (ideally honest) reasons - if we need people to knock the rough edges off of the 'product', then we need to know who they are and why they do it. For my part, I evangelise Linux Audio to anyone who'll listen. I send them URL's when they least expect it. I also conduct reading-comprehension tests to make sure they read them :) cheers R

On Sat, 2004-08-14 at 02:42, John Check wrote: Sadly not all developers have the project management skills to build a product from the code.

I've observed strong management behaviours on the projects that IMO have been successful (and I can think of 4 such projects right off the cuff). This organisation encourages me to remain involved, whereas the lack of it has led me to drop a few tools.

What's not to grok? Turn that old PII300 into a reverb :)

R

However, I am but one dude.  Post 1.0, I can help out more generally, but at the moment I am focused on Specimen, and every minute I contribute to another project is a minute I'm not contributing to my own.  I don't say this to be competitive, simply to reinforce the fact that improving our abysmal doc situation isn't something you can really expect most developers to help with; at least not so long as their own app is still critically incomplete.

At Fri, 13 Aug 2004 15:16:30 +0100, tim hall wrote: YES! Hell, ask any developer here that question and you'll get the same answer. Docs are always appreciated. However, as I said before, Specimen is getting a complete UI overhaul, so any docs you write now probably won't be relevant in a month or so. I am *not* trying to look a gift horse in the mouth here, but if you *really* want to help I think I have a better idea. Make some music (real music, finished stuff), and write docs on what you had to do to make this music. Start from the beginning: --What distro did you install, and on what hardware? --What configuration steps did you need to perform? --What applications did you use, and how did you install and configure them? --How did you use all these pieces to make music? If there are any docs out there like this, I'm not aware of them. They would be an *immense* contribution, both by showing potential users how they can make music with Linux, and by showing developers the strengths and weaknesses of the scene as it currently is. Speaking for myself, the first thing I look for when checking out music apps is music created with said apps. What does it sound like? The linux-sound.org music page has only 24 entries, and I'm NOT FLINGING MUD HERE (my own stuff sucks), but we're certainly not giving any indication of the utility of our software with them. This is because we have two many hackers and not enough UNIT-Es.

I firmly believe that the biggest, most valuable contribution anybody not currently wrapped up in a project can make to Linux audio is making music with this stuff, and writing a few example docs to get new users up to speed rapidly. If you, or anyone, or better yet, *everyone* did this, our scene would be a magnificently better place.

If you're talking about attracting people like *us*... Yes... But, if you're talking about everyone else... "Hi... I'm "Joe WindowsUser'. I just installed Linux." App_X didn't have sound, so I googled for 3 hours. Apperently, I need to run and "audio server" called "Jack". What's an "Audio Server"? I googled for three hours and found out how to use Jack. I must be forgetting something because it's still not working. After gigging all night, I still had time to google and find out that there a group called "Linux Audio Users". They will help me. Got my answer to why Jack isn't working... It was confusing and took 3 hours to figure out. But now I can connect a mic and record some music. But my keyboard doesn't work... What's wrong? I googled for 3 hours and found out I need to connect "virtual ports" together. What the hell is a "virtual port". Linux Audio Users told me to use "KAConnect" to connect virtual ports. But all I saw was stuff like 'Rawmidi 0 - EMU10K1 MPU-401 (UART)'... What the hell is 'Rawmidi 0 - EMU10K1 MPU-401 (UART)'? I connected my keyboard up the the midi port... where's my midi port in the list? The next day I got my answer... and everthing was connected up right. But they tell me I have to "load the wavetabe". Let me send an email to Linux Audio Users and see if they can tell me how to "load the wavetable". Is there anyone here that thinks we're ready for the "general public"?

> Is there anyone here that thinks we're ready for the "general public"?

no. but we are ready. which is a lot better then just a year ago. I mean the stuff you described above actually works! that's pretty amazing, I was waiting for this moment for years (well, not _this_ moment but a moment few month go when I tried to setup recording and everything worked!)

All it would take would be for one demo recorded someplace to generate a contract and people would be clamoring for linux audio.

Last Saturday 14 August 2004 01:36, John Check was like: We need to develop a better business model than that. Traditional music

industry business practice is not necessarily compatible with the aims of free music software. We bide our time and they will come begging.

cheers tim hall "It is no myst'ry / we're makin' hist'ry" --LKJ

John Check wrote: No, the Demos category links to examples of a popular art form that combines graphics, animations, and music into what is called a "demo". You want the Linux Music On-line category in the soundapps pages.

I agree wholly with whoever mentioned that what we need is a "win" with a major recording success. However, I also believe we'll get there. I've heard enough nay-saying and bullsh*t over the last ten years to know that the words "it'll never happen" are anathema to the Linux

development community. Give 'em the challenge and they make it happen. Now for the hard part: preparing the way for normal users to start working with this stuff until the user community reaches critical mass.

And in case anyone thinks it just can't happen with Linux audio software, you should have been on the computer music scene in 1986 when the Mac ruled the studios. Even the Atari and Amiga had more presence in studios than the lowly Intel-based boxes. Plenty of statements were made in the line of "Oh, the PC will never make it in pro studios, it's great for spreadsheets and word processors, but not for serious music making". Sound familiar ? My, how things do change...

So I'm confident it will happen, but I'm not so foolish to make any sort of prediction. Obviously the issue of excellent user-level docos is

glaring at us, hence my original post of this thread. The issue also obviously concerns many of us, and I hope these posts have inspired some of you to make your own contributions. Best regards, dp

Done this and made a start on docs http://wiki.agnula.org Dave Phillips has already made a damn good start on this one too. http://www.agnula.org/documentation/dp_tutorials/ I'm trying to figure out where the gaps are. No sense in duplicating effort. The fact that you're on-list now saying YES! to documentation help makes me think that Specimen deserves some attention.

I do make music with this software, but I have so far only really produced demos and test pieces, which aren't necessarily the best advert. I have already contributed some stuff to

> Done this and made a start on docs http://wiki.agnula.org

Yeah, I didn't know this info was even out there.  If these pieces were synthesized into a cohesive whole and their existence advertised in a public place that would make great inroads into acceptance. Heck, the "synthesis" could just be one page with links to the relevant docs in the recommended order of reading. Another thing to consider is whether we can obviate the need for the general installation and configuration docs.  There is no technical reason, IMHO, why we can't have a pro-audio oriented distro that requires the same low level of involvement as Knoppix.  This isn't about pandering to drooling morons, but simply respecting other people's time.  If a given task is so programmatic that we can write a HOWTO for it in recipe format, I think that's an indication that the computer should be doing this for the user automatically.

On Thu, 12 Aug 2004 09:13:02 -0400 Dave Phillips &lt;dlphilp(a)bright.net&gt; wrote: I'm a big fan of wikis. They make it so easy for the user to contribute documentation.

I don't know what would be involved wiki-izing these docs,

but I truly think it's a good idea.

However, where then should they be posted ?

Dave Phillips wrote: I'm willing to: * convert one (not too large) Howto (or similar documentation) to a wiki format (specifically TWiki) on sort of a trial basis, and * I have a Wiki site (WikiLearn) where I can post the pages (and others can also) Suggest a document that is not too big and is likely to garner enough interest so that others read and correct it. (Several suggestions are welcome, and I'll pick either the one with the most "votes" or one that seems fairly short and straightforward to convert.) Randy Kramer

On Thu, 12 Aug 2004 09:13:02 -0400 Dave Phillips &lt;dlphilp(a)bright.net&gt; wrote: I'm a big fan of wikis. They make it so easy for the user to contribute

documentation. Have a look at alsa.opensrc.org. It surpasses the official alsa site in many places wrt the available information/documentation. And if it didn't it were a great addition anyways. So while i'm not saying that every open source project should use a wiki for their primary documentation site, they should definetly think about using a wiki as secondary more uptodate user contributed documentation source..

With some effort the rather wild and often unstructured collection of information that a wiki is can be refactored and flow back into the main doc.

My suggestion would be: Transfer the above listed HOWTO's into wiki's and see what happens :)

On Fri, 13 Aug 2004 21:02:45 -0400 John Check &lt;j4strngs(a)bitless.net&gt; wrote: Yes, those are arguments often heard. Tell that to the guys at http://wikipedia.org. I strongly believe in the strengths of wikis and in nightly backups :) btw: Every sane Wiki system stores every revision of a page, so it is easy to revert evil changes. Probably easier than adding maliscious content [if not automated]..

Last Saturday 14 August 2004 02:02, John Check was like: Ah, yes. One of the best punk fanzines of all time. That _is_ what you meant wasn't it? tim hall