I'm an active documentation volunteer so this is very important to me. I have to admit that I have always found the GFDL confusing and arbitary (like its limit of how many words you can add to a front- or back-cover text). As a non-lawyer, I found the Open Publication License to be more straight-forward.
Its only drawback are the non-free options: option A requires permission for derivative works and option B limits commercial publication. However, this can be overcome by specifying "using the Open Publication License without Options A or B".
> Once you learn the networking system of getting hired, you will never do the whole resume trolling thing agian...
What happens when the economy is so bad that no one in your network works for a company that is hiring? Over the last year, I've tried a multi-facted approach: resume [e]mailing, networking, and trustworthy recruiters. None of it has worked. What's next, cold calls?
BTW, there is a book that addresses this issue: _Unlocking the clubhouse:women in computing_ by Jane Margolis and Allan Fisher (ISBN: 0262133989)
They start with the assumptions based on gender roles. For example, there is an assumption that boys "just get" math and computers. Then they address gender inequality in instruction. Boys become active learners, answering questions from the teacher. But girls aren't expected to know answers to questions, so they become passive listeners. A teacher needs to watch for this and try keep both genders actively involved in the learning process.
They also address the lack of female role models. One of their solutions was single-sex classrooms (or lab periods) and more female teachers... Definitely worth a read if you care about this issue!
> Wait, you worked at Radio Shack and are calling RCA "shoddy"? Like "Realistic", "Tandy", and "Optimus" are somehow synonymous with quality.
Actually, I bought some Optimus Pro-25 headphones at RadioShack because they were mentioned on alt.music.4-track. They were actually re-branded Koss headphones with titanium elements. They were awesome for the price!
All frequencies were audible and they had good bass response for open-air headphones. The Pro-25s were discontinued but I've read good things about the Pro-35s (also rebranded Koss headphones, IIRC).
Also Consumer Reports will sometimes suggest Optimus speakers as a good low-end buy. So, Optimus *is* synonymous with quality FWIW!
> outsourcing all of the programming jobs to India and Indonesia for 7/hr!
> I guess the CEO's do not have enough money.
You're absolutely correct. Domestic CEOs are making way too much money. Wouldn't it be cheaper if we replaced them with H1B visa workers? We could farm out the Board of Directors to an off-shore consulting firm while we're at it.
When you forget a command-line flag for ls or grep or whatever, do you type "man whatever" for its manpage or do you start digging all of its source files? Which is quicker and more convenient to use? Think about it.
BTW, I am an active Open Source documentation volunteer
> Seek out new local acts by attending live performances at small clubs, bars, and concert halls.
Well, I'd attend more local shows if...
They were affordable. I've seen great local bands for $6-12. But once ticket prices are $18+, forget it.
They were exciting. I need to hear more than a local band playing bad copy-cat versions of whatever's popular. I need to see more than a dude and his laptop.
They started earlier. Some shows open their doors at 9 or 10 pm but the band doesn't take the stage until midnight or 1 am! During a week night, this is ridiculous.
I knew what to expect. Put up audio samples on either the band's or club's Web-site.
> It's a global market, folks - if you want to keep
> your jobs and their 80K salaries, you've got to
> be better at something than your international
> competition, just like a steel manufacturer or
> anybody else who competes in the global economy.
In order for this principle to be fair, it has to be consistent. So let's apply it to everyone... So let's start by replacing the CEOs and the Boards of Directors of these firms with cheaper H1B visa labor. It's a global market, right?
From my own personal experience, lowering your salary to entry-level won't work either. Hiring managers will become deeply suspicious of your qualifications. It's like offering someone a brand-new Lexus for only $100... "What's wrong with it?"
In my experience, you're absolutely correct. But they will look at on-line help, if it is available. Check out the article I wrote about it on Advogato: http://www.advogato.com/article/374.html
Csound, the technology mentioned in the article, is free as in root beer. You can download the source code and compile and run it on Windows, Mac, and Linux. You can download Csound from http://www.cs.bath.ac.uk/~jpff/dream.html#Csound
Unfortunately Csound isn't free as in speech though. Its source code is under a copyright by MIT that restricts it to "educational and research purposes only". Analog Devices, the company mentioned in the article, has a commercial license for Csound.
For more information about Csound, check out http://www.csounds.com
> TeX has always facinated me. Let's face it, it works. I believe there is more bugs than he is writing checks for, but that said they are seldom encountered by mere mortals. If you do normal stuff it just works.
Hah! It doesn't work for "normal stuff" like hyper-links, TrueType fonts, and common image formats (gif, jpg, png, svg, etc.). I face these limitations every time I use it. This mere mortal has to use third-party LaTeX kludges.
> It really is an amazing thing, and something that every open source project should aspire to...
I hope not! The thing is a pain to configure. I tried expanding the max_strings variable and hit a limit. No matter how much changed my texmf.cnf file, nothing happened. Come to find out there was a *hard-coded* 16-bit limit to an array size in the code itself. (This bug was causing segfaults whenever I published a document longer than 620 pages.)
So it uses static memory allocation instead of dynamic. Not a bug but not really "something that every open source project should aspire to" either. IMHO.
Don't get me started on the pre-GUI, non-WYSIWIG interface either! Its interface isn't exactly a poster child for user friendliness. Personally, I'm waiing for XSL-FO technology to mature...
Notice that both the OnLamp article and the O'Reilly book don't use Wiki technology. What's that say about its relevance to technical documentation? You decide.
Re:KWord can be a good rival to Framemaker /Publis
on
KOffice 1.1.1 Ships
·
· Score: 1
> Personally I still prefer LyX for large technical documents...
> Same thing goes for document formatting... LyX with LaTex as it's backend may be different from commerical apps, it works like a charm
In my experience, LaTeX sucks with large documents! I have been struggling with a 600+ page user's manual. Whenever I exceed 620 pages, it dumps mad core. I keep getting the cryptic error messages like "max strings exceeded".
Changing my texmf.cnf is useless. The limits are hard-coded into TeX. So much for TeX being bug-free!
So now I am faced with having to hack a big convoluted mess of code that isn't even written in a normal programming language! It's "literate programming" or something... Whatever.
LaTeX definitely doesn't work like a charm for large documents!
For the love of docs, NO!!!!! Wiki might be a great solution for Weblogs but it doesn't work for technical documentation.
> Usually programmers are not very good at documentation
This is a very unfair statement and a sweeping generalization. It reveals an anti-programmer bias.
> users find difficult to get into docbook and stuff.
Users shouldn't have to use DocBook. Just give them the final rendered format. Let them send changes or additions as plain text paragraphs.
> If we were to give users the ability to do the documentation themselves, I bet they would use the oportunity.
Who owns the words? Who makes sure the information is accurate? What happens when the information in two places is contradictory? What about bored teen-agers wasting bandwidth with fart jokes? The on-line annotated PHP manual is good example of such madness.
You'd have the Tower of Babel. You need a central maintainer or editorial team to make sure to check spelling, grammar, and technical accuracy. They can also make sure everything is cohesive and has a consistent style. Otherwise, things will devolve into a confusing mess.
> The teaching from wikipedia is that you get good quality writing if enough people works on it. Something like code peer review.
Name me one successful project that blindly accepts all code patches/additions. Usually, someone submits their code to a maintainer who decides whether the code will be added. This is the way documentation should work also.
I'm a volunteer documentation writer... I've considered various ways of funding documentation efforts. (How about putting ads in the Invariant Sections of documents covered by the FDL license?)
One thing to consider, the programmers are mostly writing code for free. So writing documentation and getting compensation for it, while the programmers get none, doesn't seem right.
OTOH, maybe spreading the funding to the programmers will mean documentation writers can get some respect. Maybe it can be a way to fund the entire project.
I am a volunteer documentation writer. I write fluent English and am well-versed in DocBook. I have tried unsuccessfully to contribute documentation to various Open Source projects.
Open Source developers treat documentation writers as a step below script kiddies. (Because we don't write code?) My contributions to various projects have been blown off or ignored. There's no respect there.
Documentation is treated as something secondary. IMHO, documentation should be kept up-to-date and in sync with coding efforts. Maybe we would have more documentation if writers were treated with respect and as an important part of the team.
What about MusE and Midi Mountain? Are you saying they're not viable?
MusE: http://muse.seh.de/
Midi Mountain: http://www.music-community.ch/midimountain/
There's also Brahms (http://brahms.sourceforge.net/) but I've never been able to get it to work...
There are also many other interesting Linux MIDI apps like timidity. For a full list, check out the MIDI section of David Philip's Linux Music and Sound Apps page at http://sound.condorow.net/midi.html
As far as the technical hurdles described in the article, a solution that he overlooked was SGML with the DocBook DTD. This is currently being used by teams working on Linux and *BSD documentation.
Their are several drool-proof GUI tools that users can use like ArborText or a plug-in for Framemaker. There are others but I don't recall them all, I prefer editing by hand with a text editor.
The SGML format can be transformed into Postscript, PDF, HTML, RTF, XML, etc. The tools to do these transformations have their source code available and can work cross-platform.
Slashdot Mirror
I'm an active documentation volunteer so this is very important to me. I have to admit that I have always found the GFDL confusing and arbitary (like its limit of how many words you can add to a front- or back-cover text). As a non-lawyer, I found the Open Publication License to be more straight-forward.
Here is the Open Publication License: http://opencontent.org/openpub/
Its only drawback are the non-free options: option A requires permission for derivative works and option B limits commercial publication. However, this can be overcome by specifying "using the Open Publication License without Options A or B".
ALPO (Apache, Linux, Perl/PHP, Oracle)
> Once you learn the networking system of getting hired, you will never do the whole resume trolling thing agian...
What happens when the economy is so bad that no one in your network works for a company that is hiring? Over the last year, I've tried a multi-facted approach: resume [e]mailing, networking, and trustworthy recruiters. None of it has worked. What's next, cold calls?
BTW, there is a book that addresses this issue: _Unlocking the clubhouse:women in computing_ by Jane Margolis and Allan Fisher (ISBN: 0262133989)
They start with the assumptions based on gender roles. For example, there is an assumption that boys "just get" math and computers. Then they address gender inequality in instruction. Boys become active learners, answering questions from the teacher. But girls aren't expected to know answers to questions, so they become passive listeners. A teacher needs to watch for this and try keep both genders actively involved in the learning process.
They also address the lack of female role models. One of their solutions was single-sex classrooms (or lab periods) and more female teachers... Definitely worth a read if you care about this issue!
> Wait, you worked at Radio Shack and are calling RCA "shoddy"? Like "Realistic", "Tandy", and "Optimus" are somehow synonymous with quality.
Actually, I bought some Optimus Pro-25 headphones at RadioShack because they were mentioned on alt.music.4-track. They were actually re-branded Koss headphones with titanium elements. They were awesome for the price!
All frequencies were audible and they had good bass response for open-air headphones. The Pro-25s were discontinued but I've read good things about the Pro-35s (also rebranded Koss headphones, IIRC).
Also Consumer Reports will sometimes suggest Optimus speakers as a good low-end buy. So, Optimus *is* synonymous with quality FWIW!
> outsourcing all of the programming jobs to India and Indonesia for 7/hr! > I guess the CEO's do not have enough money.
You're absolutely correct. Domestic CEOs are making way too much money. Wouldn't it be cheaper if we replaced them with H1B visa workers? We could farm out the Board of Directors to an off-shore consulting firm while we're at it.
Let's see how *they* like it!
Could you post a URL for these job listings? Thanks.
BTW, how's the rent for a 1 bedroom apartment (at least 500 sq. feet)? How's the public transportation system?
> If you have a problem, USE THE SOURCE!
When you forget a command-line flag for ls or grep or whatever, do you type "man whatever" for its manpage or do you start digging all of its source files? Which is quicker and more convenient to use? Think about it.
BTW, I am an active Open Source documentation volunteer
What about these (mostly third-party) drivers?
http://www.alsa-project.org/alsa-doc/
All ISO9000 can guarantee is that your failures are repeatable and well-documented.
> Can't wait to see how the an economy maintained by geeks goes. I can just see 'em building their own roads
Well, there wouldn't be any road signs. Geeks hate writing documentation!
> Seek out new local acts by attending live performances at small clubs, bars, and concert halls.
Well, I'd attend more local shows if...
I remember reading this quote... "If you're not convinced God has a sense of humor, just make plans."
> It's a global market, folks - if you want to keep > your jobs and their 80K salaries, you've got to > be better at something than your international > competition, just like a steel manufacturer or > anybody else who competes in the global economy.
In order for this principle to be fair, it has to be consistent. So let's apply it to everyone... So let's start by replacing the CEOs and the Boards of Directors of these firms with cheaper H1B visa labor. It's a global market, right?
From my own personal experience, lowering your salary to entry-level won't work either. Hiring managers will become deeply suspicious of your qualifications. It's like offering someone a brand-new Lexus for only $100... "What's wrong with it?"
In my experience, you're absolutely correct. But they will look at on-line help, if it is available. Check out the article I wrote about it on Advogato: http://www.advogato.com/article/374.html
Csound, the technology mentioned in the article, is free as in root beer. You can download the source code and compile and run it on Windows, Mac, and Linux. You can download Csound from http://www.cs.bath.ac.uk/~jpff/dream.html#Csound
Unfortunately Csound isn't free as in speech though. Its source code is under a copyright by MIT that restricts it to "educational and research purposes only". Analog Devices, the company mentioned in the article, has a commercial license for Csound.
For more information about Csound, check out http://www.csounds.com
> TeX has always facinated me. Let's face it, it works. I believe there is more bugs than he is writing checks for, but that said they are seldom encountered by mere mortals. If you do normal stuff it just works.
Hah! It doesn't work for "normal stuff" like hyper-links, TrueType fonts, and common image formats (gif, jpg, png, svg, etc.). I face these limitations every time I use it. This mere mortal has to use third-party LaTeX kludges.
> It really is an amazing thing, and something that every open source project should aspire to...
I hope not! The thing is a pain to configure. I tried expanding the max_strings variable and hit a limit. No matter how much changed my texmf.cnf file, nothing happened. Come to find out there was a *hard-coded* 16-bit limit to an array size in the code itself. (This bug was causing segfaults whenever I published a document longer than 620 pages.)
So it uses static memory allocation instead of dynamic. Not a bug but not really "something that every open source project should aspire to" either. IMHO.
Don't get me started on the pre-GUI, non-WYSIWIG interface either! Its interface isn't exactly a poster child for user friendliness. Personally, I'm waiing for XSL-FO technology to mature...
Notice that both the OnLamp article and the O'Reilly book don't use Wiki technology. What's that say about its relevance to technical documentation? You decide.
> Personally I still prefer LyX for large technical documents...
> Same thing goes for document formatting... LyX with LaTex as it's backend may be different from commerical apps, it works like a charm
In my experience, LaTeX sucks with large documents! I have been struggling with a 600+ page user's manual. Whenever I exceed 620 pages, it dumps mad core. I keep getting the cryptic error messages like "max strings exceeded".
Changing my texmf.cnf is useless. The limits are hard-coded into TeX. So much for TeX being bug-free!
So now I am faced with having to hack a big convoluted mess of code that isn't even written in a normal programming language! It's "literate programming" or something... Whatever.
LaTeX definitely doesn't work like a charm for large documents!
> what is needed is a wikipedia
For the love of docs, NO!!!!! Wiki might be a great solution for Weblogs but it doesn't work for technical documentation.
> Usually programmers are not very good at documentation
This is a very unfair statement and a sweeping generalization. It reveals an anti-programmer bias.
> users find difficult to get into docbook and stuff. Users shouldn't have to use DocBook. Just give them the final rendered format. Let them send changes or additions as plain text paragraphs.
> If we were to give users the ability to do the documentation themselves, I bet they would use the oportunity.
Who owns the words? Who makes sure the information is accurate? What happens when the information in two places is contradictory? What about bored teen-agers wasting bandwidth with fart jokes? The on-line annotated PHP manual is good example of such madness.
You'd have the Tower of Babel. You need a central maintainer or editorial team to make sure to check spelling, grammar, and technical accuracy. They can also make sure everything is cohesive and has a consistent style. Otherwise, things will devolve into a confusing mess.
> The teaching from wikipedia is that you get good quality writing if enough people works on it. Something like code peer review.
Name me one successful project that blindly accepts all code patches/additions. Usually, someone submits their code to a maintainer who decides whether the code will be added. This is the way documentation should work also.
I'm a volunteer documentation writer... I've considered various ways of funding documentation efforts. (How about putting ads in the Invariant Sections of documents covered by the FDL license?)
One thing to consider, the programmers are mostly writing code for free. So writing documentation and getting compensation for it, while the programmers get none, doesn't seem right.
OTOH, maybe spreading the funding to the programmers will mean documentation writers can get some respect. Maybe it can be a way to fund the entire project.
I am a volunteer documentation writer. I write fluent English and am well-versed in DocBook. I have tried unsuccessfully to contribute documentation to various Open Source projects.
Open Source developers treat documentation writers as a step below script kiddies. (Because we don't write code?) My contributions to various projects have been blown off or ignored. There's no respect there.
Documentation is treated as something secondary. IMHO, documentation should be kept up-to-date and in sync with coding efforts. Maybe we would have more documentation if writers were treated with respect and as an important part of the team.
What about MusE and Midi Mountain? Are you saying they're not viable? MusE: http://muse.seh.de/ Midi Mountain: http://www.music-community.ch/midimountain/ There's also Brahms (http://brahms.sourceforge.net/) but I've never been able to get it to work... There are also many other interesting Linux MIDI apps like timidity. For a full list, check out the MIDI section of David Philip's Linux Music and Sound Apps page at http://sound.condorow.net/midi.html
You *can* include images using SG/XML and the DocBook DTD:
Start Screen
Start Screen
This will include either a GIF or an EPS image (depends on which stylesheet you use) with a caption...
As far as the technical hurdles described in the article, a solution that he overlooked was SGML with the DocBook DTD. This is currently being used by teams working on Linux and *BSD documentation.
Their are several drool-proof GUI tools that users can use like ArborText or a plug-in for Framemaker. There are others but I don't recall them all, I prefer editing by hand with a text editor.
The SGML format can be transformed into Postscript, PDF, HTML, RTF, XML, etc. The tools to do these transformations have their source code available and can work cross-platform.