LinuxQuestions.org
Visit Jeremy's Blog.
Go Back   LinuxQuestions.org > Forums > LinuxQuestions.org > LQ Suggestions & Feedback
User Name
Password
LQ Suggestions & Feedback Do you have a suggestion for this site or an idea that will make the site better? This forum is for you.
PLEASE READ THIS FORUM - Information and status updates will also be posted here.

Notices


Reply
  Search this Thread
Old 05-19-2012, 01:26 PM   #1
Wayne Sallee
Member
 
Registered: Jun 2011
Location: Florida
Distribution: The one that I built. (lfs)
Posts: 269

Rep: Reputation: 17
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
 
Old 05-19-2012, 05:49 PM   #2
Snark1994
Senior Member
 
Registered: Sep 2010
Distribution: Debian
Posts: 1,632
Blog Entries: 3

Rep: Reputation: 346Reputation: 346Reputation: 346Reputation: 346
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,
 
Old 05-20-2012, 12:02 PM   #3
smoker
Senior Member
 
Registered: Oct 2004
Distribution: Fedora Core 4, 12, 13, 14, 15, 17
Posts: 2,279

Rep: Reputation: 250Reputation: 250Reputation: 250
Perhaps it would be better to work with the existing project ?

http://tldp.org/
 
Old 05-20-2012, 04:53 PM   #4
nixblog
Member
 
Registered: May 2012
Posts: 426

Rep: Reputation: 53
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.
 
Old 05-23-2012, 07:18 PM   #5
theKbStockpiler
Member
 
Registered: Sep 2009
Location: Central New York
Distribution: RPM Distros,Mostly Mandrake Forks;Drake Tools/Utilities all the way!GO MAGEIA!!!
Posts: 986

Rep: Reputation: 53
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.
 
Old 05-24-2012, 09:58 AM   #6
Snark1994
Senior Member
 
Registered: Sep 2010
Distribution: Debian
Posts: 1,632
Blog Entries: 3

Rep: Reputation: 346Reputation: 346Reputation: 346Reputation: 346
Quote:
Originally Posted by theKbStockpiler View Post
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,
 
Old 05-25-2012, 07:00 PM   #7
Wayne Sallee
Member
 
Registered: Jun 2011
Location: Florida
Distribution: The one that I built. (lfs)
Posts: 269

Original Poster
Rep: Reputation: 17
Quote:
Originally Posted by theKbStockpiler View Post
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.
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
 
Old 05-25-2012, 08:05 PM   #8
TobiSGD
Moderator
 
Registered: Dec 2009
Location: Germany
Distribution: Whatever fits the task best
Posts: 17,148
Blog Entries: 2

Rep: Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886Reputation: 4886
Quote:
Originally Posted by Wayne Sallee View Post
Linux has so much potential, but is so *slowly* gaining ground.
Linux is not aiming at gaining ground, I would guess.

Quote:
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.
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.

Quote:
Originally Posted by theKbStockpiler
Another point is that Linux must be mentored. If the mentoring attitude was embraced in general it would help a great deal.
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?
 
Old 05-26-2012, 03:51 PM   #9
Wayne Sallee
Member
 
Registered: Jun 2011
Location: Florida
Distribution: The one that I built. (lfs)
Posts: 269

Original Poster
Rep: Reputation: 17
Quote:
Originally Posted by TobiSGD View Post
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?
And Microsoft Windows was released in 1985. But regardless of who was first, maturity can take place at different speeds.
Quote:
Originally Posted by TobiSGD View Post
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.

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.
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
 
Old 05-26-2012, 04:25 PM   #10
nixblog
Member
 
Registered: May 2012
Posts: 426

Rep: Reputation: 53
Quote:
Originally Posted by Wayne Sallee View Post
And Microsoft Windows was released in 1985. But regardless of who was first, maturity can take place at different speeds.
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.
 
Old 05-27-2012, 02:21 PM   #11
theKbStockpiler
Member
 
Registered: Sep 2009
Location: Central New York
Distribution: RPM Distros,Mostly Mandrake Forks;Drake Tools/Utilities all the way!GO MAGEIA!!!
Posts: 986

Rep: Reputation: 53
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.'



Quote:
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.
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.

Quote:
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?
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.
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off



Similar Threads
Thread Thread Starter Forum Replies Last Post
Linux Server documentation STeeF Linux - General 2 05-28-2004 05:14 PM
looking for linux documentation Idiotnewb Linux - Newbie 3 02-29-2004 08:34 PM
Linux Documentation Hmmyah Linux - General 3 12-09-2003 05:53 PM
Linux Documentation linuxturtle Linux - General 5 08-10-2003 10:54 PM
Linux documentation GtkUser General 6 01-30-2003 02:51 PM

LinuxQuestions.org > Forums > LinuxQuestions.org > LQ Suggestions & Feedback

All times are GMT -5. The time now is 09:26 AM.

Main Menu
Advertisement
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Open Source Consulting | Domain Registration