[SunRescue] Hardware reference re-structuring ideas.

[Chris Petersen]

> 
> Chris Petersen wrote:
> > 
> > [snip!]
> > 
> [...]
> > 
> > I definetely think there needs to be a seperate section as there is now for
> > addressing the workstations and servers as a "type" of hardware, as opposed
> > to lumping the whole thing together.  Say, a section with the basics on the
> > lineup by architecture, followed by sections in detail on each style of
> > machine, cross-linked to appendices based on host-bus architecture.
> 
> So you're saying don't lump servers and workstations together, right? 
> Just want to make sure I can still read.

Whoops, now that I reread that, I'm confused myself...

What I meant was lump all the actual machines together, just don't lump that
content together with ALL of Sun's hardware (namely I/O cards, keyboards,
etc...).  Which is an opinion probably motivated by my misreading your
original post.

However, it would be a great idea to note where things were essentially a
server versus essentially a workstation, although that line kind of blurs
with the older Sun equipment.  Sun themselves haven't been too good about
that type of delineation until the Ultra series came out.

[snip!]

> > 
> > A. Introduction (some rough history of Sun, purpose of FAQ)
> > B. Sun Hardware Specifications (Basics, bus, speed, memory type)
> >           1. Sun1
> >           2. Sun2
> >           3. Sun3
> >           4. Sun3x
> >           x. ...
> >         x+1. Chronological Reference chart
> > C. Architecture, Hardware Specifics
> >           1. Sun1 Architecture Notes
> >                 a) SUN 1 Hardware Notes/Errata
> >                 x) ...
> >           x. ...
> >           x. Sun4m Architecture Notes (maybe list of modules, etc)
> >                 a) SPARCStation 5 Hardware Notes/Errata
> >                 b) SPARCStation 10 Hardware Notes/Errata
> >                 c) SPARCStation 20 Hardware Notes/Errata
> >                 x) ...
> > D. System Options, Processors, etc. by Bus (or in the case of non-bus specific,
> >    by function)
> >           1. MultiBUS
> >           2. VME
> >           3. Sbus
> >           x. ...
> >           x. Keyboards & Mice
> 
> I'm thinking that it would be worth breaking down the individual bus
> sections into categories for each type of card (lump SCSI cards
> together, etc).
> 

Hmm, so perhaps breaking things down by function within the bus category? 
Probably worthwhile.  At the very least, a nice cross-reference index would
be good (i.e. something listing all the SCSI cards, regardless of bus?).

[snip!]

> 
> > 
> > It would be nice to take advantage of HTML for this, but whatever the end
> > result is it should also be conveniently be usable in pure text format.  By
> > that, I mean the links should not merely be hyperlinks on particular words
> > or references as much as there should be some sort of orderly reference
> > method that works both ways (not footnotes, but something that indicates
> > both visually and via hyperlink where you can get more information on the
> > subject).
> 
> This document WILL be written in DocBook SGML, for portability, and
> maintainabliity.  I know for sure that I can create HTML, PS, plain
> text, and a couple of other formats from this, so it seems like the best
> solution for this problem.  DocBook also allows you to automagically
> create indexes and Tables of Contents.  Very cool stuff...
> 

Hmm, not familiar with DocBook, but SGML sounds good to me.  Will it do any
sort of Palm format?  Would love to load my new PalmPilot up with a copy of
the reference for rescue trips...

And if it generates indices at all well, it should be trivial to generate
new variations of an index as I suggested.  I always like having multiple
ways of cross-referencing stuff.  Too much database work, I guess... 

> > 
> > Oh, and if you want a good example of how not to do it, take a look at the
> > Sun FE sometime, if you have access.  It seems like I have to bounce all
> > over the place in it to find what I'm after.
> 
> You mean the Field Engineers Handbook?  I've got one that I use as
> reference, but the oldest machines in it are I think Sun4m.  The content
> that I can put in there is a TINY bit about the SS20, and the info in
> the version that I downloaded from Mr. Bills page.  This means that I'm
> relying on you guys to help me flesh out the newer data.
> 

Yep, that's what I referred to.  The layout used by Sun in the FEH is hard
to get used to at first.  I had expected to go to one page on the SS10, only
to find out that there's a half a dozen sections to look at depending on
what you want to know.  And IMHO their organization just didn't make sense. 
I do have access to an older electronic version of the Sun FEH, so I've got
most of the SPARC era data, should we need to verify facts.

> > 
> > And if you need any help in this endeavor, Greg, give me a holler.  Me and a
> > couple of friends would be more than happy to help somehow, even if it's
> > just nailing down an organizational method.
> 
> I'll try to do most of my brainstorming on-list, to make sure I don't do
> anything really stupid, and what we get the best document possible. 
> Thanks again, and I hope to hear more from the rest of you,
> 	Greg
> 

Not a problem.  Keep us posted, and once an organization scheme is hammered
out, you might consider posting that scheme and letting people offer to
write sections for you.  Might make things a little easier, you play editor
and farm out some of the writing :)  Most of us here have had to use
Birdsall's original reference for something along the way, and I'd love to
help contribute to a successor/enhancement.