The current state of multiple groups doing some of the job is not really bad. It _will_ help if an organization like The Linux Foundation puts some weight behind a coordination of the multiple efforts.
It also will be a good idea to engage the major distribution vendors in support of the effort. Canonical and Red Hat certainly have a strong interest in the support features of their products.
The guiding group, whoever takes it on, should develop some recommendations expanding on the ones you initiated in this post. Then a documentation community coordinator should make overtures to each of the sites currently trying to write third party documentation as well as trying to get a core of writers (presumably mostly volunteer for smaller projects) ready to step up to the plate to work with the developers. It is clear that this job will be the key to general success.
Update: A quick check even identifies a Web site of a "Linux Documentation Project" where the latest newsletter was issued in 2006. So, the idea isn't new. Pulling the job all together under one umbrella...hope it works. It is a good idea.
Discussion on:
View:
Show:
My biggest issue with documentation and help forums in the Linux community is the tendency of the writers to assume everyone knows what they know. They'll reference a command but fail to mention it's in the /usr/sbin directory. They'll assume everyone knows how to "compile", or knows what a kernel is. Telling someone to install something is useless if you don't tell them how to install it. Telling someone to mount something doesn't make sense either unless you explain it. (hmm, I just thought of a joke concerning "mounting" a hard drive but I won't repeat it).
One of the popular GNU/Linux desktops is KDE, and it is also an umbrella for many coordinated programs.
As an effort to expand the quality and amount of documentation, the KDE community is sponsoring a series of "Klassrooms" and the most recent is for documentation intended for end users.
If you are looking for a place to start improving thing, this might be it.
http://forum.kde.org/viewtopic.php?f=4&t=84864&start=0
As an effort to expand the quality and amount of documentation, the KDE community is sponsoring a series of "Klassrooms" and the most recent is for documentation intended for end users.
If you are looking for a place to start improving thing, this might be it.
http://forum.kde.org/viewtopic.php?f=4&t=84864&start=0
I am very much in agreement with Jack on this one, I feel his prescribed action is definitely something that should be seriously considered. I have been using Linux now (continuously) for approx 3 - 4 years and in that time I have tried at times to move others who are dissatisfied with Windows for whatever reason, over to one form or another of Linux. My efforts fall down on many occasions because of a lack of documentation for those people to refer to. It doesn't matter how many forums or websites you can refer people to, they mostly prefer ONE point of reference where possible. Lets get this moving!
..Phil
..Phil
I too have been using Linux for about 4 years. I have suggested it to many people, some on a tight budget, and have never convinced anyone. They say they need Microsoft Office, I say all they need is OpenOffice, but they are hesitant. And as Jack says, OpenOffice has good documentation. There has to be a lot more paperback books on Linux (Ubuntu!) so that people get the idea that it is a real option. Remember that even the Apple computer doesn't compete very well against Microsoft.
Whilst I am an enthusiast for the Open Source concept, I am not a techie and I guess I'm getting a bit long in the tooth to learn. Looking back, I became relatively competent with MS windows by just using the OS over a number of years. One of the problems I have experienced is that using Linux (Ubuntu 9.1), if I experiment with the settings to learn something, I am frequently unable to restore the OS to its original state without a great deal of research and often I have to re-install the OS. My point is that for a non-technical person, Linux is not user orientated. Canonical try very hard but they are not there yet. I hope they don't stop trying because I won't stop using their software. It just won't be the main OS.
Yes, and I am a bit long in the tooth too. I only revert to MS when I need to use my scanner.
Recently repartitioned my computer and thanks to a Linux Wiki document was able to do it and restore all my OS's to working state.
I think that there should be one main book for 'basic' linux things that are common to every distro, and something else that spells out the distro specific functions and their use.
I note that there is a Techrepublic sheet of common commands. I must download that.
I usually find that MS help doesn't. But by phrasing my search correctly I can find the help I need on the forums. I know it would be an impossible task, but I would like to see all the help given on a forum reduced to a Q&A form where the solutions that work are given. This would need a place to state the specific hardware concerned.
My grouse over!
Recently repartitioned my computer and thanks to a Linux Wiki document was able to do it and restore all my OS's to working state.
I think that there should be one main book for 'basic' linux things that are common to every distro, and something else that spells out the distro specific functions and their use.
I note that there is a Techrepublic sheet of common commands. I must download that.
I usually find that MS help doesn't. But by phrasing my search correctly I can find the help I need on the forums. I know it would be an impossible task, but I would like to see all the help given on a forum reduced to a Q&A form where the solutions that work are given. This would need a place to state the specific hardware concerned.
My grouse over!
I tried the Windows version several months ago. I dropped it after a couple of weeks because I couldn't figure out some of the features. I'm one of those you mentioned who find having a separate installation for the documentation "fails to compute". Forums are useful, but it can be cumbersome looking for previously posted answers to your question.
I eventually paid for Quicken.
Edited - I agree with Jack that man pages aren't much good to newbies. However, I think there's plenty of third-party documentation regarding the operating system itself. The bookstores are jammed full of content from O'Reilly and the other usual suspects. There are several good free tutorials and guides; the old 'RUTE' is still a good intro. It's in applications where the documentation is usually lacking.
I eventually paid for Quicken.
Edited - I agree with Jack that man pages aren't much good to newbies. However, I think there's plenty of third-party documentation regarding the operating system itself. The bookstores are jammed full of content from O'Reilly and the other usual suspects. There are several good free tutorials and guides; the old 'RUTE' is still a good intro. It's in applications where the documentation is usually lacking.
I could be wrong but my impression is that the quality of documentation is higher among distributions with users who know how to troubleshoot a problem. Some of the mainstream distributions, like Ubuntu and its relatives, have documentation, but it's not on pair with the Wiki effort of Gentoo, Arch, LFS (LFS is more centred around documentation than anything else) and the alike. Mainstream distributions tend to focus on "a quick guide" approach making the gap between users and developers wider.
BSD is known for well written instructive man pages. Linux should have the same standard. The problem though is that Linux evolves and changes more rapidly than BSD, which probably makes documentation a challenge. It's no excuse however.
As already commented there have been several attempts to address this issue. Since some really good documentation already exist, some distributions already have good Wiki entries, it looks like the need would be to contact and engage the folks working with it, be it on a community or business level, in an attempt to create a backbone of distribution-independent reference documentation. If a backbone exists it also becomes easier for a community to keep their own distribution-specific documentation up-to-date. Hence I agree that it's mainly a question of good coordination.
To dig deeper into complex software solutions certain "server-standard" software offers the ultimate documentation themselves. Therefore I doubt this effort has to be wider than the bits and bolts making a typical desktop or basic server work well and be productive. In same cases though it could be good to add documentation describing concepts of how to combine different pieces of software.
Still I would say that open-source has the upper hand here. Documentation isn't on the same level as the quality of its software, but it will be much easier and more affordable to maintain such documentation. Troubleshooting proprietary software or even an operating system like Windows, is at times painstaking. A lot of documentation but it's still a guessing game since it's harder to get output explaining the issues, and much documentation is closed as a business strategy in itself. Linux could take advantage of these weaknesses.
BSD is known for well written instructive man pages. Linux should have the same standard. The problem though is that Linux evolves and changes more rapidly than BSD, which probably makes documentation a challenge. It's no excuse however.
As already commented there have been several attempts to address this issue. Since some really good documentation already exist, some distributions already have good Wiki entries, it looks like the need would be to contact and engage the folks working with it, be it on a community or business level, in an attempt to create a backbone of distribution-independent reference documentation. If a backbone exists it also becomes easier for a community to keep their own distribution-specific documentation up-to-date. Hence I agree that it's mainly a question of good coordination.
To dig deeper into complex software solutions certain "server-standard" software offers the ultimate documentation themselves. Therefore I doubt this effort has to be wider than the bits and bolts making a typical desktop or basic server work well and be productive. In same cases though it could be good to add documentation describing concepts of how to combine different pieces of software.
Still I would say that open-source has the upper hand here. Documentation isn't on the same level as the quality of its software, but it will be much easier and more affordable to maintain such documentation. Troubleshooting proprietary software or even an operating system like Windows, is at times painstaking. A lot of documentation but it's still a guessing game since it's harder to get output explaining the issues, and much documentation is closed as a business strategy in itself. Linux could take advantage of these weaknesses.
If much of the documentation effort relates to wiki efforts and may be partially distribution-bound, then probably the documentation project umbrella may have a couple of significant roles to play that will provide the central access people want or need.
It seems logical to develop an automated hierarchy index of documentation that would be effectively self maintaining.
The core central index would harvest the main documentation links for a distribution where tweaks are put in place that integrate the software into the ecology of the distribution. In turn, the distribution-level index would draw on the appropriate project documentation so that the baseline developer was in the channel.
The coordinating body would be charged with the development of specifications for this documentation framework, getting documentation-oriented contributors at each of the sub-levels to give recommendations, and needs. When appropriate, that might include a tagging system that provided a "request for assistance" that would signal the need for documentation writers on a particular project.
Those wishing to be documentation writers could then use the central index system to get connected to the team(s) they felt able to support. Where a project had financial resources available from corporate or donation backing a "write for hire" system might even be possible. The central organizing body might also be able to serve as a magnet for contributions.
Maybe a branch of WikiMedia could be viable. It wouldn't be suitable as a subset of the Wikipedia itself, but might attract writer/editors who wanted to work without the rules of references or source variety.
It seems logical to develop an automated hierarchy index of documentation that would be effectively self maintaining.
The core central index would harvest the main documentation links for a distribution where tweaks are put in place that integrate the software into the ecology of the distribution. In turn, the distribution-level index would draw on the appropriate project documentation so that the baseline developer was in the channel.
The coordinating body would be charged with the development of specifications for this documentation framework, getting documentation-oriented contributors at each of the sub-levels to give recommendations, and needs. When appropriate, that might include a tagging system that provided a "request for assistance" that would signal the need for documentation writers on a particular project.
Those wishing to be documentation writers could then use the central index system to get connected to the team(s) they felt able to support. Where a project had financial resources available from corporate or donation backing a "write for hire" system might even be possible. The central organizing body might also be able to serve as a magnet for contributions.
Maybe a branch of WikiMedia could be viable. It wouldn't be suitable as a subset of the Wikipedia itself, but might attract writer/editors who wanted to work without the rules of references or source variety.
this relies on people wishing to be documentation writers.
If there is one thing we all know about programmers, they hate documentation.
If there is one thing we all know about programmers, they hate documentation.
Programming is fun; it's like science class. Documentation isn't; it's like writing a term paper.
Some programmers enjoy it so much they'll do it on their own time for free. You won't find too many technical writers volunteering to document open source projects.
Some programmers enjoy it so much they'll do it on their own time for free. You won't find too many technical writers volunteering to document open source projects.
I don't even like commenting my own code (something which has repeatedly bitten me in a nether body region). When I do document a project, I am usually so familiar with it that I skip many critical steps, which makes my documentation useless to the end user, kind of like those man pages that don't even provide a couple of examples at the end.
When I wrote COBOL I often had one line of documentation for every five or six lines of code in the Procedure Division. (Damn, that's the first time I've typed the words 'Procedure Division" in over 15 years.)
Man pages appear to be written by lawyers who oddly seem to devote their time to linux/unix documentation project. They strive to be as confusing to the common man (no pun intended) as possible.
Good Lord, that sounds like QA. Surely this runs counter to everything that the Linux community stands for?
One of the main reasons that Ubuntu is my Linux distro of choice is that their wiki-based documentation is always useful to me. There may not be a great central authoritative source for Linux documentation, but I've had much better luck in my experience finding out how to do something non-trivial on Linux than I have with Windows or Solaris. I work with Solaris and Windows servers in my day job. For side projects I use Ubuntu server and I am way more productive because it is so easy to find documentation for server projects.
New Linux desktop users might have a hard time with Linux, but I would argue that most novices learn Windows from other users or in school, not from reading documentation.
New Linux desktop users might have a hard time with Linux, but I would argue that most novices learn Windows from other users or in school, not from reading documentation.
Linus Face down Is the Best Ops there is you can get any thing answered any time and any where and its simple. Although you engineers need to go back to school, I used to run mainframes bout 30 yrs ago... and engineers were the dimmest...I always had to tell them to turn on there terminal..oh woops plug it in first....
I couldn't agree more. This has done more to hinder the acceptence Unix/Linux based software solutions than any other single issue. I was developing COBOL applications on SCO Unix in the early 80's and found it easier to write my own OS routines than to reverse engineer the available hacks, due to the unblievable absence of documentation. MSoft would be a small niche player if it weren't for this.
Windows documentation has failures too often by only dealing with only the most obvious items for which the user will seek help. Too often I go to the manual and it tells me to do all the things I have already tried and then refers me to my support staff which is me.
In Linux it is different. For a relative novice there is often no clue as to where to look for help and when found it tells you to take certain actions. These actions are wrapped up in special Linux words about which the newcomer hasn't a clue. For the Linux guru it may be perfectly clear but for others it puts a stop to the take up of Linux.
In Linux it is different. For a relative novice there is often no clue as to where to look for help and when found it tells you to take certain actions. These actions are wrapped up in special Linux words about which the newcomer hasn't a clue. For the Linux guru it may be perfectly clear but for others it puts a stop to the take up of Linux.
have you looked at FLOSS Manuals? come join us! we are a community of 1500 people writing free docs about free software. its odd you have not heard about us since we collaborate with the fsf, google, mozilla, civicrm, sugar, etc etc etc
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.
take a look at the book selection on the GNU Press site:
Debugging with GDB: The GNU Source-Level Debugger
GNU Make Version 3.81
The Bison Manual, v. 1.875
Using GCC: The GNU Compiler Collection Reference Manual, v. 3.3
Those books will surely help a select group of people. But the truth is - those books are not going to help the new user or those who are thinking of migrating to Linux.
even on the en.flossmanuals.net site the manuals mostly cover topics new users wouldn't care to learn (with the exception of the Firefox and OpenOfice manuals).
What Linux needs is better user-level documentation.
But I do applaud what you are doing. Maybe attracting writers to cover user-level topics would greatly benefit the cause?
Debugging with GDB: The GNU Source-Level Debugger
GNU Make Version 3.81
The Bison Manual, v. 1.875
Using GCC: The GNU Compiler Collection Reference Manual, v. 3.3
Those books will surely help a select group of people. But the truth is - those books are not going to help the new user or those who are thinking of migrating to Linux.
even on the en.flossmanuals.net site the manuals mostly cover topics new users wouldn't care to learn (with the exception of the Firefox and OpenOfice manuals).
What Linux needs is better user-level documentation.
But I do applaud what you are doing. Maybe attracting writers to cover user-level topics would greatly benefit the cause?
...been saying the same thing since i first saw linux years ago... couldnt agree with you more
assuming you're a programmer. Are we limiting the use of open source apps strictly to those who understand the code?
the obvious smiley on this posting but I'm glad you rose to the bait Palmetto.
Perhaps you could put your effort into assisting with the writing of documentation or urging developers to document their software than just wasting all your time commenting on these blogs.
Perhaps you could put your effort into assisting with the writing of documentation or urging developers to document their software than just wasting all your time commenting on these blogs.
Others have made pretty much the same post. but were serious about it. You've probably been around long enough to know one or two people like that. That's why we've got the smileys. 
I pre-date the advent of smilies by just a few years and most people with a degree of wit would see my comment as an obvious jibe at the open source brigade who have been known to quote this in the past. Now, I am one amongst that order but I still know how to write a man page and I worry that we have bread a generation of programmers who see no need to document their work. This is because these projects are largely driven by the programmer and not a true development cycle which would, or should, identify the user support as an integral part of process. A certain degree of up front planning and resource management would certainly turn a sows ear into a silk purse.
- Keyboard Shortcuts:
- Prev
- Next
- Toggle
