Headline FeedsLinuxInsider Talkback
|
|
See Full Story
There's nothing like weeks of ongoing conversation on the Linux blogs to suggest a topic has struck a chord. Sure enough, that's exactly what's been going on since the middle of last month. The topic? Documentation. Not good documentation, mind you -- the bad kind. The kind Linux Today's Carla Schroder calls "Linux Bug #1." "The Internet and Google enable laziness in FOSS development because they make it too easy to abdicate the job of proper documentation to 'The community,'" Schroder began in a blog post a few weeks ago.
there is heaps of good free documentation
Posted by: eset 2009-12-09 13:44:23 In reply to: Katherine Noyes
have you looked at FLOSS Manuals?
We have been going now for about 2 years and we have many many excellent docs about free software mostly in English (http://en.flossmanuals.net) but also we have an Finnish community (http://fi.flossmanuals.net) and a Farsi community (http://fa.flossmanuals.net) and also many manuals being translated into various languages (see http://translate.flossmanuals.net/write).
for the linux community there is much of interest, but probably most interesting is the excellent introduction to the command line manual which we produced in collaboration with the FSF:
http://en.flossmanuals.net/gnulinux
You can buy it here:
http://shop.fsf.org/
We produce community authored content and we often do this in 2-5 days. For example the following were produced in 5 days :
http://en.flossmanuals.net/civicrm
http://en.flossmanuals.net/CircumventionTools
http://en.flossmanuals.net/Inkscape
http://en.flossmanuals.net/opentranslationtools
http://en.flossmanuals.net/ardour/
http://en.flossmanuals.net/theoracookbook
http://en.flossmanuals.net/sugar
and the following were written in 2 days:
http://en.flossmanuals.net/gnulinux
http://en.flossmanuals.net/GSoCMentoringGuide
http://en.flossmanuals.net/firefox
We also produce books. All of the above are available in printed form (see bookstore on the right of the front page).
We also have produced books in other languages including the recent 'How to Bypass Internet Censorship' book ( http://objavi.flossmanuals.net/books/CircumventionToolsar-translate-2009.12.01-12.02.55.pdf ) which was printed in Arabic for the recent Arabic Bloggers conference (http://advocacy.globalvoicesonline.org/2009/12/05/2nd-arab-bloggers-meeting/) held in Beirut.
We have been going now for about 2 years and we have many many excellent docs about free software mostly in English (http://en.flossmanuals.net) but also we have an Finnish community (http://fi.flossmanuals.net) and a Farsi community (http://fa.flossmanuals.net) and also many manuals being translated into various languages (see http://translate.flossmanuals.net/write).
for the linux community there is much of interest, but probably most interesting is the excellent introduction to the command line manual which we produced in collaboration with the FSF:
http://en.flossmanuals.net/gnulinux
You can buy it here:
http://shop.fsf.org/
We produce community authored content and we often do this in 2-5 days. For example the following were produced in 5 days :
http://en.flossmanuals.net/civicrm
http://en.flossmanuals.net/CircumventionTools
http://en.flossmanuals.net/Inkscape
http://en.flossmanuals.net/opentranslationtools
http://en.flossmanuals.net/ardour/
http://en.flossmanuals.net/theoracookbook
http://en.flossmanuals.net/sugar
and the following were written in 2 days:
http://en.flossmanuals.net/gnulinux
http://en.flossmanuals.net/GSoCMentoringGuide
http://en.flossmanuals.net/firefox
We also produce books. All of the above are available in printed form (see bookstore on the right of the front page).
We also have produced books in other languages including the recent 'How to Bypass Internet Censorship' book ( http://objavi.flossmanuals.net/books/CircumventionToolsar-translate-2009.12.01-12.02.55.pdf ) which was printed in Arabic for the recent Arabic Bloggers conference (http://advocacy.globalvoicesonline.org/2009/12/05/2nd-arab-bloggers-meeting/) held in Beirut.
General problem with community education
Posted by: andyo 2009-12-09 13:42:52 In reply to: Katherine Noyes
It is not enough to recruit experts (with or without pay) to write,
because they can't keep up with changes--I found that out working on
books about Linux at O'Reilly. But it is not enough to ask the
community to contribute micro-documents--that causes everything comes
out disorganized and of wildly varying quality.
My most comprehensive article on the issues is:
http://praxagora.com/andyo/professional/community_author_collaboration.html
Much more for the curious at:
http://www.praxagora.com/community_documentation/
At FLOSS Manuals (http://flossmanuals.net/), where I volunteer, we're
filling the gap with well-organized writing projects combining peer
review from the public with experts from various free software
packages. There's a very active mailing list and a lot of highly
praised output on the web site.
because they can't keep up with changes--I found that out working on
books about Linux at O'Reilly. But it is not enough to ask the
community to contribute micro-documents--that causes everything comes
out disorganized and of wildly varying quality.
My most comprehensive article on the issues is:
http://praxagora.com/andyo/professional/community_author_collaboration.html
Much more for the curious at:
http://www.praxagora.com/community_documentation/
At FLOSS Manuals (http://flossmanuals.net/), where I volunteer, we're
filling the gap with well-organized writing projects combining peer
review from the public with experts from various free software
packages. There's a very active mailing list and a lot of highly
praised output on the web site.
Late Call to Documentation
Posted by: George_Brewer 2009-12-05 13:48:21 In reply to: Katherine Noyes
I was hired for my first official tech support position because I could read the manual. Much of my IT learning curve was assisted or hampered by the manual. In over forty years of trying to make a living, the formal training got me started, but the manuals enabled me to keep the job and move on to the next.
Dear Katherine,
Re documentation - Amen!
- Please see "how to write computer programs"
at www.civilized.com/programming.html
(There may be a few other things there like the
little book on Lisp that you would enjoy.)
Re documentation - Amen!
- Please see "how to write computer programs"
at www.civilized.com/programming.html
(There may be a few other things there like the
little book on Lisp that you would enjoy.)
Bad Documentation becoming Industry Wide Problem
Posted by: snaidamast 2009-12-04 06:23:23 In reply to: Katherine Noyes
I am increasing seeing very poor documentation even with commercial products in the IT industry. In fact, on a recent task with an expensive organization charting component, there was no documentation!
The issue has always been with us in the IT field but increasingly it is becoming directly related to the growing sociological issue of deteriorating education in the United States and as a result, lowered professional expectations in the work-place. Newly trained foreign workers are not helping the matter either, with their sloppy coding habits.
Whenever I release software, I always provide professional level documentation with an email address that can be used for the product's support. Yes it takes time but it also demonstrates that you are committed to your product whether open-source or not. Good documentation is just part of the process.
However, creating good documentation takes time and effort, something that in the corporate environment is just not allocated for any longer. However, in the open-source community and the ISV community there really is no excuse for this situation.
To see a sample of what professional technical documentation should look like go to the link below and download the freely available component.
You will find a "CHM" file with a complete discussion on how to use the component.
http://tech-notes.info/2009/11/05/black-falcon-software-presents-sqlhelper-%E2%80%93-easy-to-use-net-sql-server-database-access-layer/
The issue has always been with us in the IT field but increasingly it is becoming directly related to the growing sociological issue of deteriorating education in the United States and as a result, lowered professional expectations in the work-place. Newly trained foreign workers are not helping the matter either, with their sloppy coding habits.
Whenever I release software, I always provide professional level documentation with an email address that can be used for the product's support. Yes it takes time but it also demonstrates that you are committed to your product whether open-source or not. Good documentation is just part of the process.
However, creating good documentation takes time and effort, something that in the corporate environment is just not allocated for any longer. However, in the open-source community and the ISV community there really is no excuse for this situation.
To see a sample of what professional technical documentation should look like go to the link below and download the freely available component.
You will find a "CHM" file with a complete discussion on how to use the component.
http://tech-notes.info/2009/11/05/black-falcon-software-presents-sqlhelper-%E2%80%93-easy-to-use-net-sql-server-database-access-layer/
Well, you get what you paid for.
As a professional technical writer working for a large computer company, we are paid to write high quality documenation geared toward the professional programmer and system administrator.
Writing technical documentation is a full-time job. The downside of FOSS is that no one considers documentation.
Well, almost no one. I would recommend switching to OpenSolaris if you've got a problem with Linux documentation. The documentation is much better.
http://opensolaris.com/
As a professional technical writer working for a large computer company, we are paid to write high quality documenation geared toward the professional programmer and system administrator.
Writing technical documentation is a full-time job. The downside of FOSS is that no one considers documentation.
Well, almost no one. I would recommend switching to OpenSolaris if you've got a problem with Linux documentation. The documentation is much better.
http://opensolaris.com/
no program or command without adequate documentation should be included in a distribution.
I agree at the minimum it should have a man and info page.
There is no substitution for good documentation and windows and Mac OSX has tons of it, along with video tutorials...
I agree at the minimum it should have a man and info page.
There is no substitution for good documentation and windows and Mac OSX has tons of it, along with video tutorials...
