Peyton Hall Documentation:About

From Peyton Hall Documentation
Jump to navigation Jump to search

This page is to explain a few things about the Peyton Hall Documentation system, such as why it exists, what you may hope to find here (though that can always change!) and how to go about using the resources here.


Why?

When I (Steve) started working here in the summer of 2001, the FAQ - or "Frequently Asked Questions" - was just a single HTML page with anchor tags in it linking the top table of contents to the various questions below. It was woefully out of date, and needed something to spruce it up. I started by adding information to it, but once I reached around 30 questions, I realized this was becoming cumbersome and hard to use; there was no flow from one question to another, things were just thrown together. And of course, to add a question in mid-page meant redoing all the tags below that point, and renumbering everything. This was just not going to be workable for a large scale FAQ that I wanted to deliver.

Eventually I settled on FAQ-O-Matic, which ran successfully until May of 2007. FOM got a little out of control as well, but part of that is because it's sometimes hard to define where something should go. If we're talking about using 'ssh-agent', for example, that would fall under the Unix category mostly. But in some cases, you want that information when talking about Mac OS X machines. FAQ-O-Matic didn't have a good way to let an "answer" be multi-homed, so the best I could do is link back to the other answer from wherever I was. Once Leigh and I started adding more information to the FAQ, this quickly became a problem as the new system was becoming just as unreadable as the old one.

Today, we're setting up and using MediaWiki for a few reasons:

  1. It has nice built-in features for editing pages, and can easily make a page look half decent.
    1. Like the fact that a numbered list is simple to do :>
  2. It easily allows for other users to edit pages in here, so writing documentation is no longer reserved for an "elite few" - anyone with the knowledge can share it with everyone else
  3. The FAQ-O-Matic system hasn't seen a lot of updates lately, and wasn't scaling well in our environment for what we wanted to do with it
  4. We also upgraded the web server, which we knew would break FOM, and didn't feel like fixing it (ie, this was the "kick in the pants" needed to setup something new)


What will I find here?

For starters, all the documentation from the old systems is replicated here. We've also started expanding and reworking that information to make it fit this presentation better, and you can always add other bits to it as well.


So who does the updating?

Anybody. If you have a Peyton Hall username and password, you can login to the system and edit pages, or create new ones. Do remember that anybody else can edit pages too, so if you say that Pats is your favorite place to go when in Philly, and someone else thinks Ginos is better, they could always change the page. Of course if things get too heated, we can lock a page down so this sort of thing doesn't happen, but I don't foresee that being a problem.


What if I don't have a Peyton Hall login?

Well, you can feel free to browse around, but if you really want to edit things - and if you've got a good reason to do it, then you can contact us (help at astro, which is as close to a real email address as you'll see - too much spam otherwise!) and we'll consider adding you as a local contributor to the list.


Okay, how do I get started?

Browse around and look for things that need updating. Login, and start updating them! If you need a place to play around and practice first, you can play on your own User page (User:<your username>). And at some point in the future, I'll add some help pages and such, and link to them here. Wouldn't that be a nice idea...