installation guide

[Tammy Fox]

On Fri, 2004-08-27 at 19:33, Karsten Wade wrote:
> Okay, I'm onboard for the All Hands on Deck for an Installation Guide
> for FC3.  
> 
> We have until about 20 October to have a release candidate, and this is
> possible to do if we make the pieces small enough and keep the editors
> busy.
> 
> More below ...
> 
> On Fri, 2004-08-27 at 15:33, Paul W. Frields wrote:
> > Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911
> 
> Below are some specific points, and I expanded on those suggestions in a
> patch to the Documentation Guide, as a new 7.3 Taking Screenshots.  I'll
> reply back in a bit with the steps, after I build the DB and snarf them
> from the HTML page. :)
> 
> For expediency, I'm prepared to just submit the patch to the Doc Guide,
> rolling in some other dangling issues I can include.  Tammy would see
> the CVS report and can address any mistakes and expand/modify.
> 
> > I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I
> > would like to suggest several guidelines for screenshots and any other
> > graphics (I think the GDSG may use something similar to these, IIRC):
> > 
> > 1. PNG format. Is that too obvious?
> 
> And EPS.
> 
> > 2. No wider than 500 pixels. If your graphic is larger than that, use
> > GIMP (Image -> Scale Image) or mogrify to scale the image to no wider
> > than 500 pixels.
> 
> That seems reasonable.  Make the GUI as small as it can to convey just
> what you need.
> 
> 2.1 Use the default Metacity theme to give the guides a consistent look,
> and also consistent with most user's experience and expectations.
> 
> 2.2 If you need to crop the image, do that in the GIMP to show just what
> you need.
> 
> > 3. Graphics should be included as <figure> I think.
> 
> http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure.html
> 
> That shows the format.  We kept the EPS first because of legacy jadetex
> issues, no idea if it matters anymore and I'm not tempting fate to find
> out. ;)
> 
> > Here's another one I just thought of; the GDSG mentions this as well:
> > 
> > 4. Graphics should not be included unless you absolutely *cannot* get
> > along without it. There's no reason to include repetitive screenshots of
> > parts of the interface that are easily explained in a sentence.
> > (Example: anaconda runs several progress bars when it computes package
> > dependencies, writes an install image to the drive, etc.... those don't
> > need to be screenshotted. Wait, is that a real word?)
> 

I agree as long as we also keep the following in mind (from what I have
learned working on the Red Hat IGs for 4 years and attending a usability
study where newbies were given the IG and asked to install RHL for the
first time):

1. Many people use the IG as a reference. When they get stuck, they
refer to the Installation Guide and try to find help from that point
forward. If this is the case, having a screenshot to match the one they
are stuck on helps tremendously.

2. For people following the IG sequentially from the first screen
forward, having a screenshot that looks like the one they are on helps
confirm that they are proceeding correctly and makes them feel confident
that they are performing the installation correctly.

3. Users find it useful to see sample data entered into the sample
screenshot even if it is listed in the text. Some people just learn
better visually.

> That seems reasonable.  It's nice to have one screenshot to show the
> whole GUI, if that helps.  It's probably better to have too few
> screenshots than too many.
> 

That being said, whoever is taking the screenshots should take them all
and a few extra just in case we decide it is actually needed later. This
will keep the size and sample data entered consistent throughout the
screenshots.

Tammy

> For quality of information, I find <screen> blocks (as <example>s) with
> nice, useful command line output to be better ... :)
> 
> - Karsten
> -- 
> Karsten Wade, RHCE, Tech Writer
> a lemon is just a melon in disguise
> http://people.redhat.com/kwade/
> gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41