Re: automated screenshots (was Re: more doc work, Re: completed gataxx doc)

[karderio <karderio gmail com>]

Hi :o)

On Thu, 2006-08-03 at 14:06 -0500, Shaun McCance wrote: 
> On Thu, 2006-08-03 at 19:59 +0100, Don Scorgie wrote:
> > Hi,
> > 
> > On Thu, 2006-08-03 at 19:51 +0100, Joachim Noreiko wrote:
> > <snip>
> > > 
> > > How much can DogTail automate?
> > > 
> > > Can everything about how a screenshot should be made
> > > be codified into a script? -- eg window size, document
> > > contents, menus, dialog boxes, pop-up elements etc?

Pretty much I'd say.

> > > If so, then I can imagine the following scenario:
> > > 
> > > The DocBook file contains a tag for the screenshot.
> > > This tag contains somewhere within it meta-information
> > > destined for DogTail.
> > > The documentation writer copies this to the terminal,
> > > dogtail opens a few windows, does its stuff, and
> > > shazamm!!! the screenshot has been updated based on
> > > the software on the writer's system. (Because the
> > > meta-information also says where to save the file, of
> > > course!)
> > 
> > Or, better yet...
> > Create a script (in gnome-doc-utils, of course.  Seems to be my
> > favourite place today ;) ), something like "update-screenshots".  Each
> > screenshot would have an associated dogtail script.  The
> > "update-screenshots" would run each dogtail script in turn, producing
> > the desired output.  Almost the same amount of work, but saves the
> > writers copy-pasting a series of strange commands from a file to a
> > terminal (where errors can creep in).

I see this as simply a script that will live in the help directory, call
it update-screenshots.py. Once the documentation is ready for a commit,
just run update-screenshots.py and it will open the app and issue the
commands necessary to get the shots, save them in the appropriate place,
then redo this for each locale - just one command issued to create all
the shots. In fact, I've just reread what Don said, and I've basically
repeated the same thing ;)

The script would have to be written for each app, and adapted for each
shot. Perhaps there will be common elements which could be grouped in
GDU to make the writing of scripts easier, a sort of library (Python
module). However the bottom line is there would still be much manual
coding - other than XML statements - to get this working.

Dogtail works a bit like this : it permits you, for example, to say
"Open app - Click new document - Add lorem ipsum - Show about box - Take
screenshot". You must create the script with that suite of commands
however. I feel it would be difficult to create say an XML based
language to resume how to take the shots - every circumstance is
particular, you would end up recreating dogtail.

One thing that would help would be a "user actions recorder", that
followed user actions (mouse + keyboard) and recorded them as a dogtail
based script, or in some to-be-invented XML language. This of course has
also yet to be invented.

For the time being however, I think it would be relatively simple to
create scripts to automate the taking of shots - everything is in place,
it just wants doing. 

> You silly people.  Think BIG.
> 
> If we can get perfectly reliable automated screenshots,
> then there's no reason for the documentation writers to
> be taking and saving them.  We could just automatically
> create the shots inside Yelp when the user views a page.
> And then the screenshot conforms exactly to that user's
> theme.

This of course becomes all the more sensational when you are reading
printed documentation :)

Seriously, I don't think anything like this could be at all practical.
I'm not sure it is possible to make the operation at all reliable, it
stands on too unstable ground. 

I wouldn't even recommend creating the images at build time, but rather
have a dedicated contributor run the script at the last minute and
commit the changes to CVS [1].

If we wanted yelp to do this, the user would have to have the program
installed and running in order to get the shots. If there was a problem
with the app, you would neither see the shots in the help nor in real
life. Then when you opened Yelp you'd have the app popping up and
whizzing around - not good. Then what if the program crashes, or takes
time to load or eats up resources...?

There are many things that would make messing in such a fashion with the
users apps daunting. A screenshot script potentially would work with
just a specific build - as such things changing changing compile options
and even more-so modifications in the source code, could change buttons
or menus, making the whole process grind to an early halt. What is more
the program's configuration could complicate matters.

Suffice it to say, I don't think such a thing is feasible. Perhaps some
of these problems could be overcome - in fact a similar idea, that has
been previously mentioned, could be to use dogtail to help the user
along the way, by opening dialogs and flashing buttons etc, as part of a
tutorial.

Love, Karderio.



[1] An interesting thought, for those who have nothing better to read:
running such a script at build time would not be possible : there would
be a chicken-egg problem that would make us have to bootstrap the docs,
as we would be building the program that needs to be up and running in
order to take the shots :p