[SunRescue] Hardware reference re-structuring ideas.

[Chris Petersen]

> 
> Chris Petersen wrote:
> >
> [...]
> > > > 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.
> 
> So don't put the machines in the all of the interface boards and stuff? 
> Separate out the boards that do SCSI or Video from the boards that hold
> the processor.  The only qualm that I might have about doing this for
> everything is with VME stuff.  Somebody might not be able to tell that
> their VME board is a CPU board, or a serial board, or a network board. 
> But perhaps I could just put something in there to point them to the
> correct section.  For non-vme boards, this makes very good sense.
> 

Well, I have to agree with you on the VME stuff, especially since it can
turn up in the oddest spots by itself (say a 4/6xx CPU board in a box of
Motorola MVME boards, seen it happen...).

The thing that I was getting at (and I think you covered nicely in the first
draft outline that you sent later after this email), is that you've really
gotta tackle this from a couple levels, each one increasingly more detailed
then the next.  

[Note to readers, I'm about to put a kink in the thread of this email and
grab content from a later message than the message this in reply to!]

Taking the top-level of the proposed outline, here's what I see as the
purpose of each section:

  I. Introduction.   Rough history of Sun, purpose of FAQ, author
                     information official home of this document.

	Purpose:  Exactly what it says above...


 II. Sun Hardware Specifications. Basics, Bus, Speed, Memory Type


	Purpose:  This would be a basic introduction to Sun hardware from a
                  standpoint of "I've got this box that says Sun on it". 
                  Basically, enough to give you the basics on what a Sun 
                  <insert workstation or server name here> is.  Very similar
                  to Section 1 of the current reference, but broken down 
                  a bit better, updated, and standardized from a entry
                  format point of view (i.e. standard fields like processor 
                  bus, processor speed, memory, etc.)

III. Architecture and Hardware Specifics

   
        Purpose:  This would give a further level of detail about a given
                  machine.  This could kind of take the place of what's
                  marked as the FAQ in the current reference.  The idea here
                  is to give structure to the various odds and ends bits 
                  of information regarding a particular architecture type 
                  and machine type

 IV. System Options, Processors, etc by Bus (or in the case of non-bus
     specific, by function)


        Purpose:  This section covers the basics, at the most detailed
                  level.  Prior to this section, we're dealing essentially 
                  with actual complete boxes and architecture types.  This
                  section is where we need to drill down to the actual board 
                  or component level.  There should be sections broken down
                  by bus, or where not appropriate, by function.  CPU boards 
                  should also be covered.  This is the equivalent of the 
                  board-level schematic

  V. Part Number Reference List (cross-linked back to component details)

	Purpose:  To give people who have this <insert item here> that has a 
                  Sun part number on it a way to figure out what to look at 
                  in the earlier sections for more information

 VI. Indices

	Purpose:  For quick reference for the "power" and light users of
                  this guide


That should basically cover the intent I envisioned for the outline I
proposed...


> 
> > 
> > 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.
> 
> True enough.  As a friend said to me years ago as we were just "junior
> geeks", the difference between a SPARCStation and a SPARCServer is that
> the server doesn't have a frame buffer.
> 

This is actually true of many of the UNIX/RISC hardware companies of the day
(Digital, IBM, even some SGIs).

> > 
> > [snip!]
> > 
> > > > D. System Options, Processors, etc. by Bus (or in the case of non-bus specific,
> > > >    by function)
> > > >           1. MultiBUS
>                     i.   SCSI
>                     ii.  Video
>                     iii. Network
>                     ...
> > > >           2. VME
>                     i.   SCSI
>                     ii.  Video
>                     iii. Network
>                     ...
> > > >           3. Sbus
>                     i.   SCSI
>                     ii.  Video
>                     iii. Network
>                     ...
> > > >           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?).
> 
> Sort of like how I just edited the above.  That should make looking up
> some board MUCH faster than it is now, since I generally have to do a
> search of the board number, and find something that sounds similar with
> a similar number.
> 

Yep, exactly like that.  Looks good...


> > 
> > [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...
> 
> I'd imagine that you can do that, but I'm not familiar with what formats
> are best for sending data to a Palm (although I have one myself).
> 

Just got mine, so I can't answer it myself.  But I'll look into it when
we've got some in-work project to play with.  

> > 
> > 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...
> 
> I suspect that it's not that hard, although I may have to talk to some
> people who know more about it than I do.  
> > 
> > > >
> > > > 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.
> 
> Yeah, not terribly fond of that layout myself.  It might be ok that way
> if you could hyperlink, but for paper (which I have) and plain text,
> it's NOT a good layout.  While we're on the topic (and so that Mr Bill
> doesn't think I'm nuts) does anybody out there know who I should contact
> about the copyright on the FEH, so that I might be able to include some
> content in this document, without fear of litigation?  
> 

Hmm, not sure.  Bill, do you have any idea?  I know James Birdsall's been
spotted on list recently, and I'm sure he had similar issues when he first
worked on the original reference.  Most of the information in the FEH is
probably common knowledge on this list, so I doubt there'd be too much
trouble.  The big issue might be with part numbers?

[snip! - Removed the last bit for length...]

Chris

-- 
Chris Petersen
Systems Engineer
Unigraphics Solutions Inc.		Industry Services, Mid-America Region
Email: havoc at apk.net (Personal)       petersen at ugsolutions.com (Professional)