[Spacewalk-list] Organization/Content of spacewalk wiki

Mon Nov 19 17:55:40 UTC 2012

Chris,

I'm in agreement with you on the organization and content of the Wiki.   My experience before coming to spacewalk was working with RHN Satellite Server for 3+ years and I still found it tricky to get the whole thing working.  I'm still in the dark about some of it after getting the basic functions working.

One of the best things that you bring to the table is a fresh set of eyes of the person who doesn't have a clue about it from the beginning.   My sense of the Wiki is that too much of it is based on presumptions about what people will know when they begin the process.   

I have been doing system admin work for 30+ years.  I find it more productive when developing instruction guides to do my best to assume my reader knows nothing except some bare pre-requisites.

And when there may be thousands of people reading it, also make sure the language uses as little jargon as possible especially since many of the readers won't be native speakers of English.

And, even though there may be other documentation for other tools that spells things out more generously on certain topics, I find it VERY important to include a fair amount of "how to" details when referencing tools that are necessary to complete the task.  I prefer to err on the side of verbosity and explicit examples rather than the "left as an exercise to the student" approach with reference guides and assembly instructions.

Earlier this year I had some suggestions about a way to make the instructions more useful and made suggested edits on the wiki for it.   One of the long time contributors shot me down at the time.   I considered what they had to say and decided to drop it for the time being.    After considering the comments from that time I still disagree with the other person's point of view.  From a certain perspective they are "correct."  From the perspective of making the wiki as helpful as possible to neophytes "correct" isn't the right angle to start from.  Sometimes when I'm writing I have to put myself back to the point before I knew and understood what I'm teaching so I can help the learner enter the depths of the dark forest and hand them a flashlight, a GPS unit and a walkie-talkie as they go in.

Spacewalk has many intricacies to it and it would be helpful even to those of us with some experience with RHN/Sat Server to have more of the architecture of the software laid out in structural and flow diagrams.  I'd also like to see a collection of more pointers for "difficult issues" that arise when learning to work with spacewalk. It would be nice to have a much fuller FAQ/compendium of that kind.

There are also some links on the wiki that go to the wrong place, e.g. the one for how to set up Red Hat clients.  I had to piece together setting up RHEL support from several different sites with varying degrees of accuracy since they were written relative to different releases of spacewalk and mrepo.  Is there some prohibition from Red Hat for having the complete guide for that in the wiki for spacewalk?

Whew, That is probably more than enough for this round.

Robert Boyd
Sr System Engineer | Peoplefluent
p. 919-645-2972 | c. 919-306-4681

e. Robert.Boyd at peoplefluent.com 
Visit: www.peoplefluent.com | Read: Peoplefluent Blog
Follow: @peoplefluent | Download: iPad App

-----Original Message-----
From: spacewalk-list-bounces at redhat.com [mailto:spacewalk-list-bounces at redhat.com] On Behalf Of Snyder, Chris
Sent: Monday, November 19, 2012 11:57 AM
To: spacewalk-list at redhat.com
Subject: Re: [Spacewalk-list] Can't register RHEL5 host with 'spacewalk default' key

First, I do appreciate the help, and yes, I do realize that the page I referenced is an old, CentOS page.    But it's been the most clear set of instructions I've been able to find.    Prior to two weeks ago, I'd done Red Hat work for years and never once touched RHN or anything related to it (we simply buy our required number RH licenses for all our hosts, use one to actually register a single host with RHN, then slurp down the OS + updates via mrepo with that host and the do everything else via our local mrepo setup and yum - awesome), so channels, keys, etc are all very, very confusing with no frame of reference.

I have to admit I'm not finding the actual Spacewalk Wiki all that helpful.  So far most of my knowledge has come from the aforementioned (old) CentOS page, the RHN Satellite Reference Guide (v5.5), the SW ML archives, and various websites out there.   The wiki feels very scattered in the available data and the organization of that data.  But that could just be me.

It's been an uphill battle to say the least.  But I've made it this far, so I'll go upgrade and see what happens then.

Thank you for the help.
Chris.

-----Original Message-----
From: spacewalk-list-bounces at redhat.com [mailto:spacewalk-list-bounces at redhat.com] On Behalf Of Jan Pazdziora
Sent: Monday, November 19, 2012 11:21 AM
To: spacewalk-list at redhat.com
Subject: Re: [Spacewalk-list] Can't register RHEL5 host with 'spacewalk default' key

On Mon, Nov 19, 2012 at 03:57:43PM +0000, Snyder, Chris wrote:
> 
> I have yet to find an explicit recipe for adding RHEL 5 channels to Spacewalk for PXE/Kickstart, so all my configuration has been built using lots of Googling and primarily this page: http://wiki.centos.org/HowTos/PackageManagement/Spacewalk.
> 

May I point out that this page is *not* a documentation provided by the Spacewalk project. It describes Oracle XE version which is no longer available for download and it does not correctly reflect the state of the PostgreSQL database backend support.

I understand that the CentOS documentation pages are more colorful than the Spacewalk wiki, however, the above page does not seem to have been updated since it has been last copied from Spacewalk's wiki back in 1.4 days.

The up-to-date installation instructions for Spacewalk are at

	https://fedorahosted.org/spacewalk/wiki/HowToInstall

--
Jan Pazdziora
Principal Software Engineer, Satellite Engineering, Red Hat

_______________________________________________
Spacewalk-list mailing list
Spacewalk-list at redhat.com
https://www.redhat.com/mailman/listinfo/spacewalk-list

_______________________________________________
Spacewalk-list mailing list
Spacewalk-list at redhat.com
https://www.redhat.com/mailman/listinfo/spacewalk-list