> Keeping docs up-to-date is an even more tedious chore, which gets even less recognition, but is equally vital.
As an Open Source documentation volunteer who did this, my hard work was criticized as being mechanical. I was lumped in with the script kiddies because what I did wasn't "creative". I'm glad someone out there recognizes this thankless task!
> > Writing docs is a vital chore which nobody likes and which gets little recognition.
> Sorry, but this is completely bogus. We went through this argument a few years ago: "people won't write nice GUIs for fun", "people won't write open-source databases", "people won't release open source kernels for big iron".
As an active Open Source documentation volunteer, I can vouch that the parent is 100% correct. Documentation volunteers aren't given the same peer recognition and respect as programmers... If you don't submit code patches to a project, you're the invisible man!
Here's an exercise: Think of famous Open Source programmers, how many names come to mind? Now think of famous Open Source documentation writers (who aren't also famous programmers), how many names come to mind?
I submit that Open Source development for databases and Big Iron is done mostly by companies like MySQL and IBM. Some would argue that companies will fund Open Source documentation too. But I think documentation will continue like many localization efforts, lots of thankless hard work by volunteers with little corporate interest.
How about the ability to import/export files with FrameMaker's Maker Interchange Format (MIF) format? Lots of Linux documentation is written with DocBook which can be rendered to MIF using OpenJade.
IMHO, the ability to import MIF files and tidy up their page layouts before the final render/print would make this a killer app. Other page layout programs may able to import MIF files so exporting this format would be helpful.
Man, I thought this article was going to be about how to protect your hand while bungee jumping/cycling/fishing/guitar playing/hang gliding/etc. Am I the only Slashdotter who makes it outside during the summer?
> If the government were to take into consideration more than just going with the cheapest bidder in all instances, we would get better quality.
The US government must always go with the cheapest or it will be called "wasteful"... Remember the grumbling over $1,000 toilet seats when Ronald Reagan was President of the United States?
The studies that are linked are very suspect... The linked articles mention that they use ordinary, off-the-shelf CD-ROMs. The Library of Congress study is skewed because all samples were for CDs manufactured before 1997. This is like studying current car safety by grabbing some old Corvairs out of a junkyard. (Were the CDs commercial-quality or archival-quality?)
Well, I know that hospitals use more expensive, archival-quality CD+Rs. I wonder how the results would change if they used CD+Rs like these:
> if people where interested in reading documentation, it would get written. In practice, most people (especially newbies) don't want to read.
According to the article, users do want good documentation. However, this NRTFM (PG version: Nobody Reads The Free Manual) attitude among programmers needs to be addressed. You may not want to read manuals but your users do.
Programmers that don't give a hoot about documentation won't give a hoot about their project's documentation volunteers either. I think that is problem. Why work for free if you're not going to get respect and peer recognition?
> There's simply little glory in writing a nice manual.
Agreed, think about it... How many famous Open Source developers can you name? Now how many famous Open Source documentation writers (who aren't also famous developers) can you name?
If documentation writers don't get the same respect and peer recognition as developers, what motivation do they have for working for free?
> people who write software for "fun" won't waste time writing 'boring' documentation
> Implement a Wiki that allows people to document for you.
Your reasoning is circular and therefore suspect... If writing documentation is a waste of time, why does a Wiki change that?
As a former documentation volunteer on a project that Wiki zealots took over, I can tell you from bitter experience that Wikis don't work for technical documentation. For technical documentation to be usable, it must be clear, complete, correct, and current.
Simply implementing a Wiki doesn't insure any of those qualities. As a matter of fact, Wiki zealots want entries to be unclear and incomplete to encourage participation. Wikis also fill up with contradictory information, duplicate posts, and off-topic rants.
So simply implementing a Wiki doesn't negate the need to have a dedicated documentation volunteer.
> What male would ever admit to needing such a thing [documentation]
Sexism aside, you have pointed out a real phenomenon in the Linux culture: NRTFM (PG version: Nobody Reads The Free Manual). We've gone from UNIX culture's RTFM (Read The Free Manual) to this sort of macho posturing.
Why would someone create a users manual when their work is devalued? What happens to documentation volunteers when their contributions don't result in respect or peer recognition? How would you feel seeing your hard work thrown away to implement a Wiki because it's "cool"?
> Documentation is time consuming and not very rewarding for coders. As with UI designers, we need a large group of people who get kicks out of writing documentation and there are just too few of those special people.
I'm an Open Source documentation volunteer. We're the Rodney Dangerfield of the Open Source community: we get no respect at all.
Developers assume we're too stupid to understand code. Well, we have to both understand code and clearly explain what it does.
You're right, writing good documentation is time consuming. So if someone offers to do that, treat them like part of the team. Don't devalue their contributions ("nobody reads the manual-- ha! ha!") and replace them with Wiki.
> Make doing the documentation not an 'also ran' task for those who couldn't hack it as developers, but as a really important part of the project
I'm an Open Source documentation volunteer. We exist but we have to put up with people like yourself who think we "couldn't hack it as developers". Think about it, we have to both understand the code and clearly explain what it does. This is harder than merely understanding the code alone.
The problem is that documentation volunteers get no respect at all. Linux culture has moved from UNIX culture's RTFM (PG version: Read The Free Manual) to NRTFM (Nobody Reads The Free Manual). Since the developers never read a users manual, why should they care if anyone writes one for their project?
I agree that documentation should be an important part of a project. However, Linux culture needs to change before that happens. Documentation volunteers deserve more respect and peer recognition!
> If government jobs are so great, why do so few qualified people apply to our opennings. [sic]
Because government HR systems are antiquated!
I applied for a job at one agency and had to get a login account for three different systems. I never got any confirmation that they had my resume. I also remember getting a rejection postcard for a state government job that I had applied for a year and a half back! I was already a year into a private-sector job by then.
For the record, I worked in state goverment to 2 years...
Content first, THEN style!
on
CSS for the LDP?
·
· Score: 2, Insightful
I'm an Open Source documentation volunteer. My experience in the trenches reveals this: In order for technical documentation to be usable, it must be clear, complete, correct, and current.
Usable documentation then becomes great if it is also consistent. It's frustrating to see Open Source documentation projects like the LDP spending so much time on consistency when they haven't reached usability yet. Getting there is hard work, I know.
> My numero uno criteria used to decide whether or not to use a software product when evaluting (usually open source) is whether it uses a wiki for documentation. If it does, I do not investigate that product any further.
LOL! You hit the nail on the head.
In the pre-Wiki days, I would look for a complete on-line manual. If it had a lot of empty sections, I knew the project was just a developer's plaything: d00dz, I'm too busy coding to write docs!
Maybe after the Wiki fad dies down, project maintainers will come to recognize how important documentation volunteers are. Maybe we'll be treated with recognition and respect.
I, for one, don't welcome our new Wiki kiddie overlords!
> Anyone can update the wiki. Updating LDP docs ain't that easy - and goes through a lot of (and much needed) review cycles
You're assuming that Wikis don't have review cycles. You're wrong, they're called "edit wars".
IME, Wikis are just as likely to have obsolete information. Think about it... The Wiki model is a giant litterbox where everyone dumps their crap. Wikis build up with off-topic, duplicate, and contradictory information. It's up to the reader to filter out the information they need.
OTOH, the LDP model at least has a person or team responsible for the information. Since their reputation is on the line, they are more likely to make sure the information is good. The maintainer model is the one used in the Open Source community for its source code. Would you use source code that was collected using the litterbox model? Would it even compile?
Perhaps we can boil this debate down to quality vs. quantity.
Slashdot Mirror
> Keeping docs up-to-date is an even more tedious chore, which gets even less recognition, but is equally vital.
As an Open Source documentation volunteer who did this, my hard work was criticized as being mechanical. I was lumped in with the script kiddies because what I did wasn't "creative". I'm glad someone out there recognizes this thankless task!
> > Writing docs is a vital chore which nobody likes and which gets little recognition.
> Sorry, but this is completely bogus. We went through this argument a few years ago: "people won't write nice GUIs for fun", "people won't write open-source databases", "people won't release open source kernels for big iron".
As an active Open Source documentation volunteer, I can vouch that the parent is 100% correct. Documentation volunteers aren't given the same peer recognition and respect as programmers... If you don't submit code patches to a project, you're the invisible man!
Here's an exercise: Think of famous Open Source programmers, how many names come to mind? Now think of famous Open Source documentation writers (who aren't also famous programmers), how many names come to mind?
I submit that Open Source development for databases and Big Iron is done mostly by companies like MySQL and IBM. Some would argue that companies will fund Open Source documentation too. But I think documentation will continue like many localization efforts, lots of thankless hard work by volunteers with little corporate interest.
How about the ability to import/export files with FrameMaker's Maker Interchange Format (MIF) format? Lots of Linux documentation is written with DocBook which can be rendered to MIF using OpenJade.
IMHO, the ability to import MIF files and tidy up their page layouts before the final render/print would make this a killer app. Other page layout programs may able to import MIF files so exporting this format would be helpful.
Also, how about an English language manual?
Who stole my mascot?
I must cry fowl! You're just egging them on.
Watch this one fly off the shelves.
Creating nested tables should be easier now.
Man, I thought this article was going to be about how to protect your hand while bungee jumping/cycling/fishing/guitar playing/hang gliding/etc. Am I the only Slashdotter who makes it outside during the summer?
Yes, but do they have a logo to go with that trademark yet? (http://www.netbsd.org/Changes/#logo-contest-close d)
Coincidently, an anti-static wrist strap will help with electronic grounding!
But OVC's EVM 2003 system uses Python... I guess if you don't get your candidates names perfectly aligned, the whole ballot gets thrown out!
What about on-line Java games like these from Pop Cap?
> If the government were to take into consideration more than just going with the cheapest bidder in all instances, we would get better quality.
The US government must always go with the cheapest or it will be called "wasteful"... Remember the grumbling over $1,000 toilet seats when Ronald Reagan was President of the United States?
The studies that are linked are very suspect... The linked articles mention that they use ordinary, off-the-shelf CD-ROMs. The Library of Congress study is skewed because all samples were for CDs manufactured before 1997. This is like studying current car safety by grabbing some old Corvairs out of a junkyard. (Were the CDs commercial-quality or archival-quality?)
Well, I know that hospitals use more expensive, archival-quality CD+Rs. I wonder how the results would change if they used CD+Rs like these:
Medical CD+Rs
Archive CD+Rs
> Rocketman Eric Scott shot 46 metres into the air... Scott, 41, from Dallas, Texas
Have we confirmed this wasn't the result of good old Texas chili?
> if people where interested in reading documentation, it would get written. In practice, most people (especially newbies) don't want to read.
According to the article, users do want good documentation. However, this NRTFM (PG version: Nobody Reads The Free Manual) attitude among programmers needs to be addressed. You may not want to read manuals but your users do.
Programmers that don't give a hoot about documentation won't give a hoot about their project's documentation volunteers either. I think that is problem. Why work for free if you're not going to get respect and peer recognition?
> There's simply little glory in writing a nice manual.
Agreed, think about it... How many famous Open Source developers can you name? Now how many famous Open Source documentation writers (who aren't also famous developers) can you name?
If documentation writers don't get the same respect and peer recognition as developers, what motivation do they have for working for free?
> people who write software for "fun" won't waste time writing 'boring' documentation
> Implement a Wiki that allows people to document for you.
Your reasoning is circular and therefore suspect... If writing documentation is a waste of time, why does a Wiki change that?
As a former documentation volunteer on a project that Wiki zealots took over, I can tell you from bitter experience that Wikis don't work for technical documentation. For technical documentation to be usable, it must be clear, complete, correct, and current.
Simply implementing a Wiki doesn't insure any of those qualities. As a matter of fact, Wiki zealots want entries to be unclear and incomplete to encourage participation. Wikis also fill up with contradictory information, duplicate posts, and off-topic rants.
So simply implementing a Wiki doesn't negate the need to have a dedicated documentation volunteer.
> What male would ever admit to needing such a thing [documentation]
Sexism aside, you have pointed out a real phenomenon in the Linux culture: NRTFM (PG version: Nobody Reads The Free Manual). We've gone from UNIX culture's RTFM (Read The Free Manual) to this sort of macho posturing.
Why would someone create a users manual when their work is devalued? What happens to documentation volunteers when their contributions don't result in respect or peer recognition? How would you feel seeing your hard work thrown away to implement a Wiki because it's "cool"?
> Documentation is time consuming and not very rewarding for coders. As with UI designers, we need a large group of people who get kicks out of writing documentation and there are just too few of those special people.
I'm an Open Source documentation volunteer. We're the Rodney Dangerfield of the Open Source community: we get no respect at all.
Developers assume we're too stupid to understand code. Well, we have to both understand code and clearly explain what it does.
You're right, writing good documentation is time consuming. So if someone offers to do that, treat them like part of the team. Don't devalue their contributions ("nobody reads the manual-- ha! ha!") and replace them with Wiki.
> Make doing the documentation not an 'also ran' task for those who couldn't hack it as developers, but as a really important part of the project
I'm an Open Source documentation volunteer. We exist but we have to put up with people like yourself who think we "couldn't hack it as developers". Think about it, we have to both understand the code and clearly explain what it does. This is harder than merely understanding the code alone.
The problem is that documentation volunteers get no respect at all. Linux culture has moved from UNIX culture's RTFM (PG version: Read The Free Manual) to NRTFM (Nobody Reads The Free Manual). Since the developers never read a users manual, why should they care if anyone writes one for their project?
I agree that documentation should be an important part of a project. However, Linux culture needs to change before that happens. Documentation volunteers deserve more respect and peer recognition!
> If government jobs are so great, why do so few qualified people apply to our opennings. [sic]
Because government HR systems are antiquated!
I applied for a job at one agency and had to get a login account for three different systems. I never got any confirmation that they had my resume. I also remember getting a rejection postcard for a state government job that I had applied for a year and a half back! I was already a year into a private-sector job by then.
For the record, I worked in state goverment to 2 years...
> For beginners, streaking has totally gotta come back in style.
Streaking is what happens when you don't clean your Windows properly.
Here is a DocBook generated HTML page with a picture: http://kevindumpscore.com/docs/csound-manual/adsr. html.
I'm an Open Source documentation volunteer. My experience in the trenches reveals this: In order for technical documentation to be usable, it must be clear, complete, correct, and current.
Usable documentation then becomes great if it is also consistent. It's frustrating to see Open Source documentation projects like the LDP spending so much time on consistency when they haven't reached usability yet. Getting there is hard work, I know.
> My numero uno criteria used to decide whether or not to use a software product when evaluting (usually open source) is whether it uses a wiki for documentation. If it does, I do not investigate that product any further.
LOL! You hit the nail on the head.
In the pre-Wiki days, I would look for a complete on-line manual. If it had a lot of empty sections, I knew the project was just a developer's plaything: d00dz, I'm too busy coding to write docs!
Maybe after the Wiki fad dies down, project maintainers will come to recognize how important documentation volunteers are. Maybe we'll be treated with recognition and respect.
I, for one, don't welcome our new Wiki kiddie overlords!
> Anyone can update the wiki. Updating LDP docs ain't that easy - and goes through a lot of (and much needed) review cycles
You're assuming that Wikis don't have review cycles. You're wrong, they're called "edit wars".
IME, Wikis are just as likely to have obsolete information. Think about it... The Wiki model is a giant litterbox where everyone dumps their crap. Wikis build up with off-topic, duplicate, and contradictory information. It's up to the reader to filter out the information they need.
OTOH, the LDP model at least has a person or team responsible for the information. Since their reputation is on the line, they are more likely to make sure the information is good. The maintainer model is the one used in the Open Source community for its source code. Would you use source code that was collected using the litterbox model? Would it even compile?
Perhaps we can boil this debate down to quality vs. quantity.