Mr. Miyagi and the Install Doc

[nerdcomic]

First off VL is awesome, and you guys rule. For me, VL worked right off and setup all my hardware perfectly the first time. Now my relic of a computer is faster and more reliable than ever and it doesn't get slower and more unstable the more I use it. Back when I was using the old MS "BritneySpearsXP", it wasn't uncommon to boot up and find that my OS had shaved off its own desktop and checked itself into the Betty Ford Technical Support Center. Thanks to all you guys that have helped make my life easier by developing this distribution of Linux.

I'd like to join the community and help with development. Unfortunately, my coding skills are like a college frat boys cooking: I can barely code hot water for Raman. However, I do have some suggestions when it comes to the transition from commercial to open source operating systems for the newbie non-developer.

Jargon Reduction:
Right now, the tech jargon among developers and Linux users is thicker then Mr. Miyagi's accent and this can be a real obstacle for those who don't know a command prompt from a bucket of KFC. A lot of documentation assumes a beginner knows basic tech terms, when most of us don't have the slightest clue.

What I'm saying is... think of the dumbest, most incompetent developer you've ever worked with, get him drunk, then hit him in the head with a 2x4 a couple of times and slam his face in a car door, and even then, he would be more capable than most MS Windows users who've never run any open source OS.

As far as the installation documentation, here are some suggestions:

Re-write to improve clarity:
For instance, the section that talks about partitioning says that if you want to dual boot with Windows, you will need to create the logical Linux partitions under an Extended Partition. What the heck is the difference between a logical and primary and extended partitions? It gave an example of a partition breakdown for a full VL install, but how much space should I use for this extended partition for a dual boot? It didn't say, so I had to guess. I allotted a gig. Is this too much? Too little?

Less Choices, more direction:
I know that VL is all about choices, but the last thing a beginner needs is to have to make choices about stuff they nothing about. For instance, a lot of documentation reads like this:

"Well, in order to do so and so, you're going to need to download a so and so program. You can use this one, but this other one is also good, just be sure you get version x or later. And then there is this one made by so and so company, and they've really made a lot of improvements from the last version. I, myself use this one, but it's text-based. Other text based so and so programs are..."

How in the world is someone who has never used a so and so program going to be able to figure out which one best fits their needs? This also happens during the install. I had to choose between options like this:

What type of journal system thingy...
"Which would you like? System A has always been very good. However System B is also good. System C is experimental, but so far, has been very good..."

LILO...
"Where would you like to install LILO? Putting it here is the easiest... sometimes. But you can also put it here, here, or here, which work equally as well..."

While all of these options might be great for experienced users, they are mostly a source of stress for a newbie. I went through the whole thing praying that I got stuff right and wouldn't have to reinstall. After about 6-7 attempts, I finally got it right... I hope.

Relevant Examples:
Here's an example of a confusing example:

    *  /dev/hda : First Master IDE drive.
    * /dev/hdb : First Slave IDE drive.
    * /dev/hdc : Second Master IDE drive.
    * /dev/hdd : Second Slave IDE drive.
    * /dev/sda : First SCSI device.
    * /dev/sdb : Second SCSI device.

What's this mean? It was in the partition section of the install doc and was meant to help me understand how to partition my hard drive. I managed to get VL installed, but I still can't figure out what this has to do with Linux partitioning during an install.

Don't get me wrong. I'm not dogging on whoever wrote the installation doc. Truth is, it's one of the better installation docs out there. However, what I am trying to say is things that make perfect sense to a developer don't always make sense to people who are used to Windows doing everything. When someone becomes interested in moving over to Linux, they are generally looking for the quickest and easiest route from point A (Windows or Mac OS) to point B (Linux). It's a lot easier when someone says, "Do this, then this, and then this... now you're running Linux" as opposed to "Well, you can this, OR this, OR this, then you need to choose between this and this, but only if you want this, then move on to this... etc..". 

To help with this, I offer a couple of suggestions. First, have a writer, as opposed to a developer, craft the docs that are meant for beginners. What I think would work best would be to pair a writer who had little, to no experience with VL with a developer who knew it all. That way, the doc would contain all the necessary info, but be clear of all the tech jargon.

Next, break the install doc into three experience categories:
1) What's Linux again?
2) I've used other distros, and want to try VL.
3) Just get me the code...

Tell the beginners what to do, because they probably won't know enough to make informed choices. Give the intermediates all the choices and technical examples of how they can pimp out their install. And the last category probably won't need to read any docs, so just point out the quickest route to whatever piece of code they're looking for.

Let me know what you guys think, or if I can help in any way.

[Lyn]

It is very useful to have a fresh pair of eyes look at the documentation - Linux can be very good at documentation but you can also drown under it or alternatively some critical part is missing.  So any observations you have would be most welcome.  I have installed too many distributions and have installed Vector too many times to be objective on this.

[nerdcomic]

Cool! Thanks for reading the posts of a newbie. After I posted, I was worried that maybe someone would take it the wrong way and think I was being overly critical. Truth is, I love playing with VL. I've been messing around with it all night and seeing all the cool stuff you can do that Windows would never allow. I really like it, and want to help get more people involved. The OS is great. Since I can't code, I figured I'd help develop and improve the space between the programmer and the newbie.

[rbistolfi]

Hi nerdcomic, I enjoyed reading your post. I am sure the devs will keep your ideas in mind, no reason to "take it wrong". I think the idea of different levels of expertise for the installer is very good. The partitioning part is the hard one for every newcomer, and it is really hard to solve, since an automatic partition script is a bit dangerous. All the data in your disk is in risk, and the user has to still decide how much free room wants to make for the new os.
I hope to see you around.

PS: There is lot of stuff to do beyond writing code, you started pretty well

[bigpaws]

Hi Nerdcomic,

Welcome to Vector Linux. You certainly hit a couple good areas of concern from a
new users experience. The critique is clear and to the point. There is no thoughts of
bashing Vector that I interpreted, so no reason be worried. Any critique is welcome.

Thinking about writing. It is hard to get good writers, maybe this would be an area that
you can contribute?

Bigpaws

[nightflier]

Welcome nerdcomic.

You will find that the VL community is pretty grown up. The members don't spend their time looking for opportunities to get their feelings hurt and blast anyone who may disagree with them.

I concur with your observation that documentation lags behind the technical evolution. It is a whole different skill to write good documentation than it is to write good code. And I would think that, unlike the exciting world of developing new hardware and bleeding edge software, writing documentation becomes a thankless grunt job of recurring maintenance. Just about the time you finish your masterpiece on "The complete guide to every possible customization in KDE", you are two versions behind. I'd love to have a manual to follow, but have conceded that Internet search is my best resource. If you can help in that area, everyone here will cheer you on. 

[GrannyGeek]

Partitioning is a difficult topic for everyone the first time you do it. It doesn't matter whether it's Windows or Linux. I know I did a lot of research the first time I had to partition a drive way back in the very early '90s, and I still quaked in my boots. Of course, I had backed up my entire system and had a plan in place just in case the whole thing turned out to be a disaster. (It worked without problems, by the way.) But after doing it a few times, I got to actually prefer plain old FDISK to the prettier Partition Magic and friends because I knew exactly what FDISK was doing, whereas I didn't always know what Partition Magic had up its sleeve.

I don't think it's possible to take the confusion out of partitioning for a newbie. You just have to bite the bullet and learn how Linux identifies drives and partitions. Without that, disaster lurks, as people who have wiped out Windows without intending to can attest.

That said, I do think that the partitioning step is probably the most unfriendly part of the installation. I like cfdisk quite a bit, but as an FDISK veteran, that's not surprising. I'm sure I'd be scared to death if I had never partitioned anything before.
--GrannyGeek