I believe screenshots look bad once scaled down. As I think Shaun said, if a window cannot be resized so that it will fit, there must be a problem with the UI. I suppose scaling can be acceptable in some extreme cases, but I would say only as a last resort (you can change your screen resolution for screenshots ;).

Rather than adapting the shot to look unwindowish, yelp could dress screenshots so as to help distinguish them from windows. Perhaps a simple border could suffice, maybe integrating the legend. I think it would be interesting to look into this.

A couple of lesser points :
* I believe the style guide, quite rightly, recommends against effects such as fading. I'm pretty sure it says no drop shadows at least.
* I don't think we accept animations at all (not saying that we shouldn't).

Love, Karderio.

I oppose scaling for purely practical reasons.  Text becomes incredibly difficult to read in resized screenshots.  Yes, I know, the purpose of a screenshot shouldn't be to present all the details of the interface.  But try this experiment: Take a full windows screenshot of your favorite application.  Now open it in the Gimp and scale it by 70%.  Now apply a Gaussian blur with a 2px radius.  That's what your grandmother will see.

Now, on the other hand, it is entirely feasible for us to implement scaling automatically inside Yelp.  We can then scale the screenshot to fit nicely in your window, giving you as much detail as your window width can accomodate.  And then we can add a little button that expands the image, for when people inevitably say "What the hell? I can't read this crap!"

On cropping, this should absolutely be done when you want to exhibit one part of a window.  There is no use cluttering up your screenshot with irrelevent parts of the interface.  I think (and this is just my publication intuition) that fading is the most elegant and effective way to crop.  Not only does it look nice, but it gives the impression that it was lifted out of the surrounding interface, and shows some of that interface for context.

The GDSG's guidelines against screenshot decorations are perhaps too all-encompassing.  I don't know the original thoughts that went into it, but my general admonition about decorations is not to do them for the sake of making things fancy.  That happens a lot in technical documentation, unfortunately.  But to the extent that visual effects can be used to increase reader comprehension and decrease user confusion, we should consider them.

As for animations, I'm not sure we currently have a suitable format for that.  (I would like to make use of DocBook's videoobject some day, embedding some GStreamer love for demos.)  I haven't looked at MNG for a long time, so I don't know where it's at, or where Gecko's implementation of it is at.  And GIF is pretty much permanently out the window in my book.  (On the other hand, if we can figure out sufficiently unhacky DocBook to mark it up, we could allow authors to provide multiple images, and Yelp could do the animation itself with some pretty trivial JavaScript.)

There seems to be slight confusion here about the point of reducing large screenshots. The goal is not for people to be able to read any of the window contents, but -- as the Style Guide already suggests -- to reassure people that they have the correct program or window. As a comparison, Office 12's "Super Tooltips" will feature window screenshots reduced to 10% or less.
<http://blogs.msdn.com/jensenh/archive/2005/12/02/499371.aspx>

I don't see why GIF should be "out the window" beyond August 11th. Explain?

Any thoughts on how much fading for cropped edges?

Another argument for scaling/cropping/autoscaling is that it prevents horizontal scrolling in the Yelp window. The optimum width for comfortably reading on the screen is narowwer than most full-size screenshots of an app window.

Am I really the only person who reads documentation on the web to get a feel for the application?  Anyway, we can do this in Yelp.  I've filed bug #349109 to add the auto-scaling functionality.

Regarding that Office 12 screenshot, imagine for the moment that you're using a large font and a large icon theme, because your eyesight isn't as good as it used to be back when you used to see Bobby Darin in concert.  An image that size might not even be recognizable anymore.  It'll just be a blur of gray and blue blobs.

As for GIF, I wasn't aware the last of the problematic patents would expire this August.  (Thanks Wikipedia!)  Honestly, it's not like I've been waiting with baited breath, eager to be able to use an inferior image format again.

Anyway, with all this talk of fading edges, and with fancy rounded corners on all the latest Metacity themes, using an image format with an alpha mask seems pretty silly.

After posting my last comment, I had a scary thought: that no matter what amount of fading we specify for cropped edges, everybody will do it differently.
Is fading something that yelp could add automatically, and if so, how would we specify which sides it's needed up?

(BTW: Shaun, yes, I too read docs on the web to see what an application is like.)

I think that for the time being, we should scale to 75% or whatever fits in a window that's set for comfortable reading. By the time we have implemented funky scaling in yelp, most screenshots will have become obsolete due to UI changes anyway.

>"Am I really the only person who reads documentation on the web to get a feel
for the application? "

I'd say "not !" :) To me, there seems to be one important difference between online help (Yelp) and docs on the web or in a book (published content) : the user has the app in front of him with Yelp (a priori). I would deduce that more screenshots would be useful for published content.

Is there a way to markup extra screenshots for published content ? Is this recommendable ?

Love, Karderio.

There are provisions in DocBook for doing such things, though we don't currently have support for that in gnome-doc-utils.

http://www.docbook.org/tdg/en/html/ref-elements.html#common.attributes

Basically, we'd have to define an application of the condition attribute.  Note that condition is pretty much defined to be an implementation-dependant way of doing conditional processing, and there is no specification on how to use it.

There are screenshot guidelines on the wiki, although screenshots are mostly discouraged for user help due to needing a lot of work to translate and exactly reproduce the existing screenshot. The new guidelines are:

https://wiki.gnome.org/DocumentationProject/Screenshots