LinuxQuestions.org
Review your favorite Linux distribution.
Go Back   LinuxQuestions.org > Forums > Linux Forums > Linux - General
User Name
Password
Linux - General This Linux forum is for general Linux questions and discussion.
If it is Linux Related and doesn't seem to fit in any other forum then this is the place.

Notices


Reply
  Search this Thread
Old 09-25-2010, 03:39 PM   #1
SaintDanBert
Senior Member
 
Registered: Jan 2009
Location: "North Shore" Louisiana USA
Distribution: Mint-20.1 with Cinnamon
Posts: 1,767
Blog Entries: 3

Rep: Reputation: 108Reputation: 108
which documentation do you "need" most; "want" most?


I'm a technical writer. I want to contribute to Linux community in general and the *-buntu distribution family in specific. Naturally, I want to spend my effort where it will be most valuable. This leads me to ask:

If you could have one [new] piece of documentation, what would it cover?

My preference? I'm looking for documentation of any sort that details the event-driven, automatic, on-the-fly, dynamic discovery, dynamic creation system and X-windows initialization.

Here is some documentation terminology that I find useful. It is not in common use around linux, but it worked for me over a 25 year developer career.
  • "User Manual" -- (also, "Operator Manual") material that starts with tasks that an end-user wants to accomplish tells how to use the application to accomplish those tasks.
  • "User Guide" -- (also, "Cheat Sheet") similar content to a User Manual only very brief and to-the-point.
  • "Man[ual] Page" -- (specific to unix-family systems) material is a command-line implementation of User Guide content along with command syntax synopsis and some explanation.
  • "Reference Manual" -- material for the end-user that lists all of the features and options with descriptions of what each feature and options will accomplish. Think, "push this button, that happens."
  • "Maintenance Manual" -- a subset of the Reference Manual that describes errors and problems along with known evasive or corrective action.
  • "Theory of Operation" -- similar content to the Reference Manual, for power users, maintainers and developers. This material explains HOW things work and WHY it works that way.
NOTE -- I worked for IBM(tm) briefly in the late Sixties. At that time their mainframe documentation used a similar organization. It made much sense to me. I borrowed it. A similar organization (of thinking if not implementation) served me well.

Merci d'avance,
~~~ 0;-Dan
 
Old 09-25-2010, 06:15 PM   #2
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
If you write an intentionally comprehensive guide, I will worship you!

Computer documentation is the worst so everything except basic Bash guides which I believe are the only thing covered well. How to dual boot is incomplete but most people figure it out.

I have to start new paragraph for C. Trying to learn C even after some interpreted ones is still a cluster F@$k. What exactly is a header file for example ? From the definitions I have read it could be almost anything.I know if I don't put certain things in it, certain things won't work. I think the best approach on this one is to enlist some one that has written a compiler and find a group of people that have no indepth computer knowledge to implement it with no paraphrasing or help. If it needs paraphrasing ( a teacher) throw it in the garbage and find another compiler writer who can express their subconsciouness through to their intellect. If you can't find one just have a book written about how to write a compiler. It would probalby be faster and easier to learn to write a compiler anyways, seriously!

The make file/function documentation gets a grade way at the end of the alphabet. To begin with , why is anyone adding the confusing overhead of something the FIRST time you try to compile it. WHO CARES about automating the second compilation on the first compilation? I have read everything on the Web I could find and my knowledge of it is still below vague.I have a clue of what to search for after reading every guide I could find.


A book on Linux in general would be great for GUI and basic user topics. Not to go past Bash and how to have the same functioallity as M$. Compiling source code should be a decent part of this.

Most of the certification guides I have read look like training for a paralegal. They don't teach you anything. They expect you to "memorize and recall".



Best of wishes on your endeavors!

Last edited by theKbStockpiler; 09-28-2010 at 01:27 AM. Reason: spelling
 
1 members found this post helpful.
Old 09-25-2010, 10:45 PM   #3
SaintDanBert
Senior Member
 
Registered: Jan 2009
Location: "North Shore" Louisiana USA
Distribution: Mint-20.1 with Cinnamon
Posts: 1,767

Original Poster
Blog Entries: 3

Rep: Reputation: 108Reputation: 108
I appreciate your frustration and would welcome the opportunity to address many of your concerns.

Since I've taught C and C++ programming at the university level, and taught it in industry, and used it for [too] many years, let me see if I can offer some light and heat amid the smoke.

1. "make" and "make files"

When you type "make {target}" here is what happens (in general, simplistic terms.) Make reads the "make file" looking for rules. Each rule says, "to create {target} you need file AA, ..., ZZ;
If you don't find a copy of {target} use the set of commands to build one; If any of AA, ..., ZZ is newer than {target}, use the commands
to build an up-to-date copy." This gets complicated because the make file usually treats every AA, ..., ZZ as a target as well. In this way, if any one file gets changed, make will discover all of the related and affected parts, build only those things that are out of date, and create a fresh copy of {target}. The alternative involves building everything every time. As the number of source files increases, the more desirable it is to avoid building parts that did not change.

Your executable depends on the object files for all of the parts either individually or in library files.

Each object file depends on its source file, its header file(s), and other object files or libraries
2. "header files"

You are right that a header file can contain almost anything. ("Almost" depends on your compiler and a few other details.) As you write a program, you declare variables and data structures needed by the functions that manipulate that data. As a minimum, you need these declarations in each source file that contains functions that use the data. Another thing you need to declare is the function prototypes for each function. Your main program will need these so that you can call those functions in the first place. Enter the "header file".

You write a file that contains declarations for the data and the function prototypes. The file does not contain any statements that will actually allocate memory for data. Thus you will find the struct or class statements that describe a data item.

In your file of function source code, you #include your header file, and all of those declarations are available.

In your main program file, you #include the headers file, and your program sees the data declarations and "forward references" for each of the functions.

When you compile and link, all of the references come together.

And along comes make to help you keep all of this straight every time you change something.
Did I add light or simply more smoke?
~~~ 0;-Dan
 
2 members found this post helpful.
Old 09-26-2010, 01:59 AM   #4
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
I'm glad I come across as frustrated. It has its benefits.

I guess I do understand those two concepts because your explainations of them are the same as the ones that I built myself from spending forty hours researching.

Another topic not well covered is Firefoxes about:config. All the issues with printing Web pages and hardly any info on what the configurations are for in the printer section. Firefox is so huge! Why should anyone have to scrounge around the net to see if a third party has figured their stuff out by trial and error when their people wrote it? I don't like to approach computing by FOOLING around with it. It's a waste of resources if there are people that can mentor you through it. It' not a positive means of being resourceful or creative. If we could stop struggling to go over the same ground, we would have ample time to address real problems.

Editted: I forgot about Auto-Tools. A book on Auto-Tools would look great on an endtable, good reading too!

Virtual File System also

Thanks for the Totorial!

Last edited by theKbStockpiler; 09-28-2010 at 01:23 AM. Reason: add Auto-tools
 
Old 09-26-2010, 04:14 AM   #5
H_TeXMeX_H
LQ Guru
 
Registered: Oct 2005
Location: $RANDOM
Distribution: slackware64
Posts: 12,928
Blog Entries: 2

Rep: Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301Reputation: 1301
I agree that FF about:config is not very well documented, I mean I have no clue what some of the things mean in there.

I'd also say that the ffmpeg docs are not complete either, many things are left out and not explained.
 
Old 09-28-2010, 10:47 AM   #6
SaintDanBert
Senior Member
 
Registered: Jan 2009
Location: "North Shore" Louisiana USA
Distribution: Mint-20.1 with Cinnamon
Posts: 1,767

Original Poster
Blog Entries: 3

Rep: Reputation: 108Reputation: 108
re: large numbers of config options

Firefox has chosen to use the about:config approach to storage and manipulation of the large number of settings available to tinker with a running Firefox. I believe that Mozilla web site(s) offer explanations about the most common settings the end-user cares about. Settings that are important to Firefox developers might be harder to find.

Linux has hundreds of options and is very tinker friendly. In other words, if you want to tinker, you can. There are alternatives platforms where the end-user has little ability to affect operations. I agree that there are features where the end-user must make a large number of config decisions, and that all those decisions can be daunting. In my experience, these features are fewer today than they were when I started with linux over ten years ago. They get fewer still with each major release. I'm not being flippant when I say, "your mileage may vary" where your specific need for config tinkering is concerned. Just like a an auto with a fancy powerful engine likely requires more routine adjustments to keep it running well, so too your choice of linux features might make higher demands for tinkering.

Think about your typical modern automobile. (Even if you are not a driver, it provides a metaphor that most find approachable.) Most people approach their car, climb in, start it and go. The only options that they routinely manipulate involve wipers(on, off), stereo(on,off), lights(on,off), climate(heat,cool). However, there are literally hundreds of other options that most don't ever care about. It depends on your choice of vendor, some cars are extremely difficult for the end-user to adjust and tinker. Other cars are very tinker-friendly. So, too, with linux. Some distributions are designed to minimize (not limit) the need for end-user tinkering. Other distros demand that tinkering. Regardless of your distro choice, applications present their own set of tinkering demands.

There are workstation features that make sense to "just work" out of the box. One might think that printing would be one of them. Gone are the days (daze? grin) when printing was mostly text on paper. There are an amazing number of settings required so that what appears on paper mostly looks like what appears on screen regardless of which printer and display features the end-user happens to install. CUPS helps by generalizing the way that applications view printer hardware and connections to that hardware.

Cheers,
~~~ 0;-Dan
 
Old 10-26-2010, 11:34 AM   #7
SaintDanBert
Senior Member
 
Registered: Jan 2009
Location: "North Shore" Louisiana USA
Distribution: Mint-20.1 with Cinnamon
Posts: 1,767

Original Poster
Blog Entries: 3

Rep: Reputation: 108Reputation: 108
bump
 
Old 10-26-2010, 11:55 AM   #8
djsmiley2k
Member
 
Registered: Feb 2005
Location: Coventry, UK
Distribution: Home: Gentoo x86/amd64, Debian ppc. Work: Ubuntu, SuSe, CentOS
Posts: 343
Blog Entries: 1

Rep: Reputation: 72
This is why I love gentoo - every other distrobution i've tried to use is just lacking, or presumtious in their documentation. I'm sure theres many problems even with the gentoo documentation, but to me, it got me up and running, and I still refer back to it randomly when I have a new kernel upgrade, or something else which I know the documentation will lead me correctly.

However, more annoying than no documentation in _incorrect_ documentation. I want to scream and shout sometimes when I have a problem which goes on for hours, only for someone to say "Oh, sorry, the manual is wrong". How much time must be wasted by people trying things which are simply never going to work due to incorrect instructions must be astronomical. However you'll always choose the manual over no manual, as it seems the most sensible choice.
 
Old 10-26-2010, 12:29 PM   #9
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
Why is this thread not a sticky?

Grub has a lot of outlines for guides but nothing useful. They are like sales brochures and you cant configure anything with a sales brochure.Can't someone who wrote the code for it explain how to configure it so we don't have to reverse engineer it from source? Couldn't my time be spent better not reinventing the wheel every time something has to be learned? Grub tutorial; "Configuring Grub from Scratch", with examples.
 
Old 10-26-2010, 12:51 PM   #10
GrapefruiTgirl
LQ Guru
 
Registered: Dec 2006
Location: underground
Distribution: Slackware64
Posts: 7,594

Rep: Reputation: 555Reputation: 555Reputation: 555Reputation: 555Reputation: 555Reputation: 555
The subject of this thread is a great one, an important one. Unfortunately it seems it is and always will be an uphill struggle. Why? Because the software developers often write documentation the same way they write software -- it's terse, efficient, and written for people who will understand it without interpretation.

This is fine in/of itself, but not great for the general public, or average joe, or semi-skilled tinkerer. And evidently, most software developers do not (for whatever reasons) have on call a decent writer with whom they can spend the time necessary to create nice helpful documentation in ${English:-language} that most people can understand.

While I think I tend to do OK understanding most documentation I encounter (eventually), one key element that would improve ALL documentation, is more examples! It's one thing to read & mostly-understand a concept, or what a command is supposed to do, but an example of it in action (sample code) would go a long way. Something like `tc` comes to mind: the man pages are terse, with zero examples. Examples would be wonderful.

Another thing is X. I think X documentation is generally pretty good, and pretty complete. But some of it is out of date, and when working on an actual real system (a machine, server, desktop, whatever) more than just X docs are required. It often takes a combination of docs, for X, for the driver being used, and possibly for the OS being used, in order to get a working X. Therefore one good X document is only part of the puzzle for X.

Due to the above sorts of things, and other things such as more desire to work on the software than the documentation, AND certainly the rapid pace of development of new & existing software, the documentation gets out of date quickly and this whole cycle perpetuates..

It's a commendable effort on behalf of the OP. Kudos.
 
Old 01-05-2011, 03:47 PM   #11
SaintDanBert
Senior Member
 
Registered: Jan 2009
Location: "North Shore" Louisiana USA
Distribution: Mint-20.1 with Cinnamon
Posts: 1,767

Original Poster
Blog Entries: 3

Rep: Reputation: 108Reputation: 108
... follow-up about Documentation Use

Where do you find your Linux and *buntu-specific documentation?

I start with
  • docs from the distro repositories
  • man pages and info pages
  • docs from the *buntu site online

Cheers,
~~~ 0;-Dan
 
Old 01-05-2011, 04:35 PM   #12
johnsfine
LQ Guru
 
Registered: Dec 2007
Distribution: Centos
Posts: 5,286

Rep: Reputation: 1197Reputation: 1197Reputation: 1197Reputation: 1197Reputation: 1197Reputation: 1197Reputation: 1197Reputation: 1197Reputation: 1197
At the moment I can't think of any important Linux documentation that is flat out missing.

Linux documentation needs a lot of improvement, but in most cases that means improving the presentation of information that from an expert's point of view is probably already there.

The common major flaws in Linux documentation are:

1) Document the syntax and say next to nothing about the meaning.

2) Jump into the extreme details that an expert would need to be reminded of, but never have any summary or overview that would let a beginner figure out what the details mean. This also include qualifying introductory phrases so carefully to avoid being incorrect for some small subset of the full range of uses, that the phrases become meaningless to anyone who needs them.

3) Failure to use examples. Humans learn better by extrapolating from examples than by applying logic to a combination of precise rules. Most documentation of command line programs ought to start with some simple examples of common uses and the full command line that works for each such common use.

For a powerful example of total failure on items 2 and 3, plus significant failure on 1, look at the man page for find. Imagine you didn't already know how find works (or try to get a friend that doesn't know find to use that man page to figure out how to do a common task in find).

Last edited by johnsfine; 01-05-2011 at 04:37 PM.
 
Old 01-05-2011, 11:36 PM   #13
chrism01
LQ Guru
 
Registered: Aug 2004
Location: Sydney
Distribution: Rocky 9.2
Posts: 18,344

Rep: Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746Reputation: 2746
1. Definitely need more examples on (almost) all man pages etc
2. MUST have date stamps on all docs, so we know when it was correct (assuming it was in the first place !).
SW and docs change rapidly; undated docs just confuse the issue by telling you to do stuff that has been deprecated or changed since it was written.
If this became a 'std', maybe google could add a 'latest date' or 'sort by date' option to its search params.

The RHEL manual at www.linuxtopia.org is pretty good on explanation and examples.
http://www.linuxtopia.org/online_boo...ion/index.html
 
Old 01-08-2011, 02:05 PM   #14
SaintDanBert
Senior Member
 
Registered: Jan 2009
Location: "North Shore" Louisiana USA
Distribution: Mint-20.1 with Cinnamon
Posts: 1,767

Original Poster
Blog Entries: 3

Rep: Reputation: 108Reputation: 108
Quote:
Originally Posted by chrism01 View Post
...
If this became a 'std', maybe google could add a 'latest date' or 'sort by date' option to its search params.
...

Next visit to google.com, look on the far left for "more search tools" or similar.
There you can find ways to search by date. There are several pre-programmed such as
"last week" and "last month". There is also a custom option where to name a start and end
date. Sadly, too much money and politics enters into presentation of search results for a
sort by date feature to every work without tinkering behind the scenes.

Hope that help,
~~~ 0;-Dan
 
  


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
Telling people to use "Google," to "RTFM," or "Use the search feature" Ausar General 77 03-21-2010 11:26 AM
net working eth0 eth1 wlan0 "no connection" "no LAN" "no wi-fi" Cayitano Linux - Newbie 5 12-09-2007 07:11 PM
Standard commands give "-bash: open: command not found" even in "su -" and "su root" mibo12 Linux - General 4 11-11-2007 10:18 PM
"Xlib: extension "XFree86-DRI" missing on display ":0.0"." zaps Linux - Games 9 05-14-2007 03:07 PM
LXer: Displaying "MyComputer", "Trash", "Network Servers" Icons On A GNOME Desktop LXer Syndicated Linux News 0 04-02-2007 08:31 AM

LinuxQuestions.org > Forums > Linux Forums > Linux - General

All times are GMT -5. The time now is 04:35 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