Linux Documentation
 

Often it is difficult to figure out how to do something because the available documentation is not clear, and often out of date. When writing documentation it is easy to think it should be clear to everyone else, when to others it's not, and it's easy to leave out details that you assumed everyone knew what you were referring to.

I think it might be a good idea to create a forum for the purpose of creating and updating Linux documentation.

The goals should be to maintain an ongoing improvement in readability, grammar, spelling, overall clarity, and up-to-date of said documentation.

Each person that posts a new thread with a document in the first or second post would revisit that thread to edit that document as people post in that thread pointing out areas where it needs improvement.

If the original poster is no longer around, and improvements need to be made a second person could post a new thread picking up where the Original Poster left off.

This idea is similar to a Wiki but each document would be edited by one person, and that person could know when someone has posted a need for clarification by subscribing to the thread.

If a person has abandoned his thread, and someone else has created a new thread and doing a good job at it, a moderator could edit the first thread by adding a statement stating that it has not been kept up, and posting a link to the new thread.

What does everyone else think?

Wayne Sallee
Wayne@WayneSallee.com

I don't really see the advantage over a Wiki - which we already have on LQ (http://wiki.linuxquestions.org/wiki/Main_Page). I feel it would also add extra work for the mods in managing/merging/editing the new threads. Would the extra effort you envisage not be better put to just upgrading/updating the relevant wiki article?

Also, putting your email address in your posts is up there in the top 10 best ways to get a metric ton of spam sent to your inbox... ;)

Regards,

Perhaps it would be better to work with the existing project ?

http://tldp.org/

Totally agree, always contribute back to the top level or direct source it relates to such as TLDP or if distro specific to such things as Ubuntu Docs or FreeBSD Handbook - to name a couple.

Interesting concept
 

I don't think the absolute best Documentation is utilized to the extent it should be. Another point is that Linux must be mentored. If the mentoring attitude was embraced in general it would help a great deal.

I floated around the idea of a webpage that had links to other web pages to the best guide tutorial on a certain aspect. This is because there are some great guides and tutorials on small subjects but not the entire subject of Linux. You would be reading one guide and it would be linked to other guides with links on related subjects that are part of the main subject like Wikipedia only reasonably comprehensive. Most Wikipedia articles are like and old Paper Style of Encyclopedia of being only good to find the specific terms and use other guides tutorials to paraphrase it, sort of a vocabulary lesson without the meanings, just the words.

Sometimes I read guides and tutorials that I'm already familiar with and I can't fathom how the author expects a novice to get anything out of it.

Linux Documentation is why Linux has 1 percent of market share on Desktops. A Movement on Linux Documentation is the answer. I just recently found a (Intentionally Comprehensive) link on CLI Power Management Commands after searching on and off for a while. What a waste of time. The answer was easy. I think Linux Developers want Linux to stay a boutique O.S so they can remain the wizards. If you start a project to further Linux Learning IM me.

This sounds remarkably close to flaming, whether or not you meant it that way.

I shall reply once and once only on this line of questioning: Linux is not trying to get market share. Maybe Canonical is, maybe Red Hat is, but the majority of distros aren't. They are innovating for its own sake, trying to improve the experience of using computers.

By all means, start a movement to improve Linux Documentation - but work with people who have already done such things, so we can progress together rather than compete.

Well done for finding the article, but I fail to see the link between wizardry and the difficulty you had in finding the article. And I don't think wizardry is as you represent it: I never ever fail to be wowed by any piece of awk code that Grail writes, but he certainly is not some necromancer (to extend the wizard metaphor) who is hoarding his knowledge to make sure no-one else writes code as good as his.

Kind regards,

Yep I know exactly what you mean.

Linux has so much potential, but is so *slowly* gaining ground. Sometimes things that should be so simple are made so complex.

When I tell people about Linux, I tell them that Microsoft is like a person mature in years, but going down hill, and Linux is like a teenager; Linux can do circles around Microsoft, but has not matured as much, and is a bit buggy.

Better documentation and mentoring would get more people involved, and Linux would soar.

Wayne Sallee
Wayne@WayneSallee.com

Linux is not aiming at gaining ground, I would guess.

You realize that the current Windows family (Windows NT) was first released in 1993 and Linux in 1991? So actually Linux is older than the current Windows family?
About the buggy part: May it be that you use Ubuntu? My Slackware installations are definitely not buggy. Well, not more than I expect, since I run a development version. Maybe you should try Slackware 13.37 and see how stable Linux can be.

By the way, any member can contact you via your user profile, so you don't have to post your email address in every post.

Regarding documentation. Even if I am using Slackware, the first place for me to look for documentation is the Arch Wiki, it is the most complete collection about configuring Linux I have found so far. Another good source for documentation are the Gentoo Wiki and the Slackbook. If you look at these three sources you will find almost all you need.

So you mean literally thousands of people spending their time to help other people on countless forums and IRC channels to achieve what they want or teach them things and give hints to learning material is not mentoring enough? What else do you want?

And Microsoft Windows was released in 1985. But regardless of who was first, maturity can take place at different speeds.
No I don't have Ubuntu, though I have tested it out, and have a number of different linux flavors. But yes I have noticed that slakware does seem to have more documentation than other distros. But slackware documentation is not always in line with my distro that I use, though I have been able to use a number of slackware documents in working with my distro.

Wayne Sallee
Wayne@WayneSallee.com

The irony is that Microsofts first Business OS was in fact a UNIX clone called Xenix which surfaced about 1980, approximately five years after MS was founded.

Clarifications
 

For the record it's not Just Linux Documentation that could be drastically improved but Most Documentation in general.


For lack of a better term I use (Market Share). Instead of saying 'No one uses Linux except on Servers', I say 'Linux Desktop has almost no Market Share. It's a shame that the Documentation is not Intentionally Comprehensive.'



I use this axiom to support this belief.

How is it possible that a person can accomplish a task and NOT explain how they did it ,NOT being able to transfer the knowledge of how they did it or NOT willing to transfer the knowledge of how they did it? There are an endless amount of physiological reasons and no physical reasons for this.

I personally don't count Forums as Documentation.

Examples : The Linux Tutorials ; Bad Documentation. 'As an intermediate user sometimes I browse The Linux Tutorial web site for advanced concepts , indirectly understand what the authors are implying , remembering trying to understand this poetry as a novice and getting wise and moving on to Comprehensive guide/tutorial.

Larry Webb; and others ,A Linux Mentor. 'LW provided the missing piece of my usage of Grub Legacy. He undertook my problem as his own and took me step by step through it.' Larry's framework approach helped me build my own conceptual framework needed to understand Grub Legacy. If you have multiple post in the same thread until the problem is solved or have directed the thread author to the information to do so you are a Mentor and you are of coarse a great person. :hattip: