[Spacewalk-list] Organization/Content of spacewalk wiki

[Jan Pazdziora]

On Mon, Nov 19, 2012 at 12:55:40PM -0500, Boyd, Robert wrote:
> 
> 
> 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.
> 

The person who reverted your change was me:

	https://www.redhat.com/archives/spacewalk-list/2012-August/msg00010.html

I'm all for making the documentation more accessible, more clear,
better in general. Fresh eyes of people who are fresh to Spacewalk
are great for that.

But as a person who tends to answer quite a lot of questions of people
who hit a roadblock during installation or upgrade, and who has gone
through the task of reviewing the HowTos and making them up-to-date
for a couple of Spacewalk releases, I also need the instructions to
be correct and stay correct -- because it will often be me who will
be helping people when they get into problems.

Over the years, we had to fix bunch of modifications made by people
who thought well and hit an issue and provided a fix or workaround
on the wiki ... except that fix or workaround only worked in their
situation, on their OS, with their particular setup. Or the instruction
was no longer applicable the day the next Fedora release came out.
Or people removed steps that were not needed on their installation
that we knew were essential in other environments (and were clearly
marked for specific OS or situation). People add their bits to the
wiki and go away. We need to maintain the wiki.

I don't think our goal can possibly be duplication of the
administration details of RHEL, CentOS, SL, and Fedora. If we go that
path, Spacewalk's wiki will soon look like the CentOS Spacewalk page,
describing situation as it was one and a half years ago, not as it is
now.

If you think more information is needed in some steps, please link to
the original documentation, rather than copying exceprts from it. If
you'd like to completely revamp the structure, please do it in
separate pages so that it can be reviewed before it overwrites the
live instructions.

Please note that each Spacewalk release can be installed on four OS
versions not counting the RHEL clones, with at least two database
backend setups, more if you consider external databases. We like to
think the flexibility we provide by supporting fairly broad set
of deployments is good. Any suggestion that would make the
documentation more clear while still supporting the nontrivial set
of installations is most welcome.

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