Re: Work in progress documentation design

[Petr Kovar <pmkovar gnome org>]

On Thu, 30 Jul 2015 10:52:38 +0100
Allan Day <allanpday gmail com> wrote:

> Petr Kovar <pmkovar gnome org> wrote:
> ...
> > > We're assuming that getting started was primarily intended to help
> > > existing GNOME users migrate to GNOME 3, and that the majority will
> > > have done so.
> >
> > What about users migrating from other environments and systems? Are we no
> > longer interested in providing them with a good getting started experience?
>
> I've already stated that I think that static images provide a good experience.

Well, that doesn't really answer my question about users migrating from
other systems, but anyway, thank you for your input.

> Arguing that documentation without video is substandard seems odd,
> considering that the vast majority of GNOME's documentation is text
> only.

We are not talking about the vast majority of documentation here, we're
talking about getting started documentation. And that's very much different.

The idea that new users can learn much easier when being provided with
video content and that videos can do a much better job at communicating
new concepts is not really my invention. Just compare our video tutorial
with getting started content provided by other projects or companies. If
they do the job right, they very likely provide videos as part of
their getting started experience.

> > > But I'll reiterate what I said previously - I don't think that the
> > > switch from video to static images is a significant downgrade.
> >
> > I don't see static images as a good replacement for videos. You'll be having
> > hard time trying to explain some concepts without the help of animation.
>
> Can you provide a list of concepts that you think can only be
> communicated using video?
 
I'm talking about the concepts covered in getting-started. Also, I'm not
arguing that they can *only* be communicated using videos.

As for replacing them with static images...  The thing is that you can
create super long procedures with many steps - which is not really a good
practice in technical writing - or you can end up with many different topics
explaining all the concepts, which is pretty much what we already provide
in gnome-user-docs, but I don't really know how to design and develop the
getting started content using text and static images only *and* make it
better than what we have now.

Cheers,
pk