See:

• AboutThesePages

<Currently, no significant content below this line.>

Contents

Notes

Moved here from a comment on Support.InstallationProblems

Johnathan,

Glad you got it installed now! Your links (above) were interesting, but I was more than HaHaOnlySerious about the newbie (or quick reference) version of the documentation.

I made quite a few pencil notes on various sheets or scraps of paper as I did the installation of the 20010315 beta, and then tried to incorporate some of them on my private TWiki. (I was a little afraid of showing my ignorance by attempting to modify the "real" (online) TWiki documentation, but even more afraid of butchering that documentation and being flamed.)

Next time I do an install I may rewrite the documentation on line (although it has been improved since I made my last install). If the installation goes perfectly and alles es clar, I probably won't, but otherwise will simply copy the "real" online documentation to another page and start adding notes (or whatever else it takes) to make it clear for me.

One particular point, I sort of like the Army teaching style of "tell them what you're going to tell them, tell them, tell them what you told them" but with the caveat that the reader should be able to clearly recognize which is which, almost something like the following (irrelevant / made up example) (which is extreme, I'll admit):

Example moved to NotesOnWritingDocumentation.

Step III: Format an ext2 Floppy

The next step is to format a floppy with an ext2 filesystem. If you can do that without further instruction, please do so and proceed to step IV well maybe I'm getting a little carried away

Reminder: Commands to Format an ext2 Floppy

If you need a reminder, here are the typical commands to format an ext2 floppy in Linux:

fdformat /dev/fd0H1440
mkfs -t ext2 /dev/fd0

Newbie Explanation: Formatting an ext2 Floppy

If you need more explanation or handholding re formatting an ext2 floppy, you will not find it here -- here are some links which may help you:

• Rute ...
• ...

Step IV: Mount the ext2 Floppy

...

Hmm, I know this is way off topic, I guess I'm trying to sell you on the idea of writing up your newbie version of the TWiki documentation. And one of the points I can remember that was particularly confusing was about editing the httpd.conf file -- I saw the steps telling me what to do (can't recite them here) then later saw the example -- it took me a while to realize that they were the same -- at first (and for longer than I care to admit) I thought I had to do both.

Another confusing thing I can remember was the sed script to change the locker of the files -- I didn't know what a locker was (or maybe that RCS used one), the sed script didn't make any sense to me (even to the level that if I typed it in verbatim I was still confused -- did I have to make some change to it, or were there backticks, or what -- there was something but it's sort of mute now because it has been changed to a Perl "script" which, at least at this point, makes sense to me.

And then of course were the permissions!! Forget all the confusion I experienced. Some I guess was knowing when I had to be root to do something. Another might have been the idea that the entire directory path has to allow the desired permissions.

Oh, and really knowing how a path on the hard drive corresponds to a path in the httpd.conf file. And then, if you throw a virtual web server (virtual address?) (??) into the mix (or some address rewriting (to shorten the URL), I'm still extremely confused.

---

Since we are veering way off topic, I found an example, although I was unable to find the Red Hat page where I got it and just provide the link. Anyway, compare 'man rpm' to this:

Source: Help File Library: Red Hat RPM Guide

In general, normal usage of the rpm command can be summarised as follows:

Installation/Upgrading/Removal

To install a package type: rpm -ivh

• ex. rpm -ivh somepackage.1.1-4.i386.rpm

To upgrade a package: rpm -Uvh [filename]

• ex. rpm -Uvh somepackage.1.1-5.i386.rpm

To remove a package: rpm -e [packagename]

• ex. rpm -evh somepackage

Also for upgrading or installing some packages you may need to use additional flags to force the install happen. It is only recommended to use these if you know why these flags were needed. --force will overwrite files that are owned by other packages. --nodeps will install even if the package needs packages that were not installed.

To see if a package is installed: rpm -q [packagename]

• ex. rpm -q somepackage

To get info on an installed package: rpm -qi [packagename]

• ex. rpm -qi somepackage

To list which files belong to a package: rpm -ql [packagename]

• ex. rpm -ql somepackage

To see what package a file belongs to: rpm -qf

• ex. rpm -qf /usr/bin/some_executable

One can usually join various query commands together, so rpm -qil will give info and list all the files in the package.

To look in a rpm filename that isn't installed, you tag on the p to the query line.

• ex. rpm -qilp somepackage.1.1-4.i386.rpm will list the information and the files contained in somepackage.

Notice that in only one place did the instructions exceed more than one or two lines. Also, these instructions are for the most common transactions with rpm, rather than every blessed thing that can be done with it!

-- JonathanSmith - 20 Feb 2003

---

Randy,

PatternsForTeaching provides another elaboration of principles that may be helpful, especially the AlbertEinstein quote.

A curious thing about MattWilkie recent ridiculing of my asking for help; he knows how to write helpful documentation (see example below), e.g.,

• QuickInstall is near the top of the page after a brief introduction
• Steps are numbered, start with verbs (use active tense) and are brief
• He uses a clean layout with lots of WhiteSpace
• He breaks out configuration code
• He even is friendly and inviting.

Go figure!

Johnathan,

Thanks for the link to Patterns for Teaching -- that and some of the pages linked to it look very helpful (as well as your summary of what makes MattWilkies stuff good.

I'm not sure he intended any ridicule -- I'd have to go back and look to see what he said -- he is cognizant of the tension between developers and users, both with limited time.

Don't forget - if you change something, do it in GoodStyle and follow the TextFormattingRules.

-- RandyKramer - 24 Feb 2003

---

Contributors

• () RandyKramer - 20 Feb 2003
• () JonathanSmith - 20 Feb 2003
• <If you edit this page: add your name here; move this to the next line; and include your comment marker (initials), if you have created one, in parenthesis before your WikiName.>

Page Ratings