Where are they?

[dunbar]

I have used Linux since the late 1990s, so for a moment, lets just ASSUME I'm a newbie.

Well, really, I am a newbie when it comes to researching how to configure a program in Linux (no, I'm NOT talking about httpd nor Apache, no, not referring to system level configuration - there are books for that: Linux in a Nutshell, LPI certification study guides, etc).

I'm talking about applications being configured. Hydrogen, Scribus, different chat clients; I usually NEED deeper configurations than KDE control panel applets can get to.

Speaking of commandlines, I'm ok at the commandline; I'm just not finding any consistency in locating documents for applications which I've installed over the years. I could list them all, but you'd still not see what I REALLY mean.

How does it help ANYONE when each application needs to have its documents scattered over 5 or more possible locations? /usr/doc, /usr/local/doc, /home/*, http://www.weird.web.domain.name.here/~directory.which.has.been.missing.for.several.year s, http://LDP.org/application.name/5.releases.older.than.the.release.i.need/help.configuring, and the list goes on.

But wait - there is more!
Sometimes there is an entry in the man pages... sometimes that man page entry says to go to info for the latest information (but info contains a cut and paste of the man page which sent me to use the info system), sometimes I have a document called README in /usr/local/doc, but that document tells me to go to a website OR that document is not readable (e.g., try running more *.pdf or less *.html at the command line).

So many different ways to create and store documents, and it is NOT great to be a newbie. Linux documentation needs consistency; I don't care who thinks their idea is a better idea, the newbie AND the veteran sysadmin would benefit from having documents that were available ON THE LOCAL SYSTEM, documents that were CURRENT, and documents that were readable at the commandline.

Before you say that smarmy 'Why not offer to document programs' or take a judgemental view and dismiss this post as a rant:
1] I HAVE offered to document and got NO instructions from ANYONE.
2] TENS of thousands of application documents are now MY responsibility to track and update?
3] I can't read C/C++/PHP/Python/ whatever.

I believe the best man for the job of documenting any application is the person (or a member of the team) that wrote the application. The documentation task would get a coder to look over the code (as they should already be doing) and determine which variable accepts which parameters. I can't begin to guess how to document the code.

So, in closing, I say the coders should be held to taks for creating the documentation for their code. I know the GNU team felt that way, at one time.

[Freston]

As John Cleese:

"It's getting better"

[dunbar]

I see someone moderated....

And for Freston:
Thanks.... That was helpful!!

[dunbar]

I wasn't simply ranting, people. This documentation situation is totally out of hand, and because I dare speak, I'm the subject of denigration? And mods - kindly put this thread back where I posted it, since I'm not merely venting.

[oz]

No, the thread stays here. The other forums are for people asking for help with specific issues.

[techieMoe]

I wasn't simply ranting, people. This documentation situation is totally out of hand, and because I dare speak, I'm the subject of denigration? And mods - kindly put this thread back where I posted it, since I'm not merely venting.

I'm not the one who moved this thread, but I see no reason for it to be anywhere but the Coffee Lounge. You're simply expressing your opinion, not asking for help with something. That is the purpose of this section of the forum.

What do you propose to do about this documentation problem? I agree that documentation is generally the most ignored part of any software project (free or commercial), but what process do you propose to fix it?

Without a plan to change the perceived evil, your post is indeed just a rant. Don't get me wrong, that's perfectly fine; I rant about things quite a bit. I just don't see this thread as anything more than that.