The Linux Newbie Replies: WFM?

Thanks to Sensei^ for sending us a link to a piece about dealing with new Linux users. Given the gigantic growth of Linux over the last year, this is an issue within the community: How do we deal with this influx of population? Everyone recognizes the need for more documentation, but what's the best way to do it? If you've got an opinion about the whole schmeal, click below and add to the conversation.

Comments

Better documentation, not necessarily more.

[dustpuppy]

My first real foray into Unix (ie install OS, help users etc) was with FreeBSD. I learnt about Unix in general as well as the specific FreeBSD issues as I went along.

Two years later I delved into Linux and have been using it for a year and a half.

Although Linux has an extensive set of documentation and I wasn't a novice to Unix by then, I still found FreeBSD easier to learn even though I was virtually new to Unix.

I found that the documentation for FreeBSD was organised very much like a manual which was great to start with as I could work through it as I installed a system. The topics were also general such as 'disks', 'backups', 'serial communications' and it was easy to quickly find what you needed.

The Linux docs are organised by a specific 'need' and while it is great when you are after a solution to a specific problem, it is too unstructured for a newbie.

A newbie needs to be lead through the topics in a general fashion so that they can gain an overall picture - Linux docs don't really give a good overview.

It's 5am so I'm not very coherent at the moment - so i apologise if my opinion isn't very clear. I can't really give specifics (at least I can't think of specifics at the moment), but that is my general feeling about what makes Linux that little bit more difficult for newbies.

Maybe...

[Mechanical_Governor]

...if every Linux user dropped the attitude and helped the newbies instead of getting off on how superior they are because they know Linux.
Simply reading the manual/readme/whatever doesn't always work. If someone is used to OS xyz or 123 jumping to Linux takes a little help. I think that the Linux community doesn't want average Joe to use Linux because that would put average Joe on the same level.


"If you do not believe in the freedom of speach for those who you despise, you do not believe in it at all." -Noam Chomsky

A guide to writing documentation for newbies

[jd]

In 10 easy steps...

1. HOW-TOs need pictures. Newbies can read, but they can't necessarily relate. If they had the experience -to- relate, they wouldn't be newbies and probably wouldn't need HOW-TO's either.
2. We need MANY MORE translations. Linux is international. The documentation isn't.
3. Related to the above - the "man" command needs to support multiple languages, and the "man" documents need to be translated.
4. Installers need better "back-stepping". Not everyone has one of those globes from "7 Days". It should be possible to undo exactly one step, at ANY time.
5. There needs to be optional "automagic" configurations. One-button installation, for given categories of user, taking you right the way through with NO further interaction. The computer picks sensible partition sizes, arranges things just so, configures -everything- and installs all the packages that that category of user would want, given the size of disk, speed of processor and amount of RAM.
6. Linuxconf is good, but doesn't cover -nearly- enough areas. It needs to do MUCH more.
7. Automatic upgraders, such as the one Debian has, should be standard, and should be capable of downloading alien packages.
8. Documentation should be in hypertext format. Either "classic" hypertext, using links, or in the more mundane (but truly original) folded document style. Seeing too much can blind even an expert, never mind a newcomer.
9. X configuration is -still- the worst part. This MUST be made more automatic, with automatic graphic card detection & identification as far as humanly possible.
10. PPP is not as friendly as it could be. I've lost count of the number of times either PPP, chat, or one of the GUI tools, has barfed, with no error message, no core dump, no message in the log and no information as to even that there's a problem other than ifconfig shows PPP isn't there and 'ps axuw | grep pppd' returns a big, fat zilch.
11. For "newbies" who are at the point of wanting to do kernel upgrades, there needs to be a script which sets the defaults to intelligent values. I mean, let's face it. If you're running a 386, it doesn't make any sense for the Linux kernel menuconfig script to start by assuming you want to work on a Pentium II. Sure, you might, but doesn't it seem likely that you are more likely to want a kernel on the system you're using? Once you tell it, sure, it can retain the value for next time, but initially, sensible values would seem sane.
12. The same goes for everything else. Sensible Defaults, PLEASE!!

(Ok, so I lied about it being 10... :)

Documentation format

[ajs]

The fundamental problem right now is that no one knows what format their documentation should be in, and many people just punt or write minimal documentation as a result. HTML is useless for creating any kind of structured searching (unless you layer a documentation standard on top of it). roff has a decent documentation standard for UNIX, but no one likes it any more. texinfo is nearly impossible to manage since it requires sophisticated tools that don't play nice with anything that anyone actually uses. Plus, it requires a central table of contents which is difficult to manage automatically from un/installation scripts.

I've been thinking about it, and I really believe that Larry Wall's greatest contribution to the world has been POD (not Perl, itself). POD is a very simple documentation format that can be used to follow the roff-ish manual conventions of UNIX, but the format is so simple that it can be converted to man, HTML, texinfo (though texinfo standards usually want more prose than a UNIX manpage has), plain text, etc. This is a very nice solution for someone who's ambitious enough to go through the entire Linux documentation base (HOWTOs, FAQs, man pages, texinfo, PostScript, etc) and convert it all to this one format. Then each distribution could choose it's pet format to render in (probably *both* HTML for the new people and man for those who have "man -k" hardwired into their brains).

It would be nice to layer a few additional features on top of POD:

T which takes a term or phrase and indicates that this particular section of this document defines that term in a way that should be indexed globally. This is not quite the same as LaTeX's indexing. More of an HTML "A NAME=" sort of thing, but where HTMLs mechanism could be called a pull model, T would be a push.

H which takes a semi-colon separated URL and filename. The filename is an image that should be used as a figure in the document (numbered from one on). If the URL is provided, it is the location that should be referenced when users view this document in a text-only setting. The lack of images in POD is the only thing I don't like, and I know that it's quite unreasonable to expect that all Linux users (or UNIX users in general, for that matter) will be viewing documentation under a windowing system, but it would be nice to be able to show diagrams and other figures when the possibility exists.

Given these minor changes, rewriting the documentation would consist of converting all of the extant documentation over to text and then hand-hacking it back to POD (POD is very nearly plain text, with minimal markup that makes HTML look like a general purpose programming language).

Any thoughts. Should I just duck now?