Re: Work in progress documentation design

[Petr Kovar <pmkovar gnome org>]

Hi Allan,

Thanks for sharing your ideas with us. I've got a few comments...

On Wed, 22 Jul 2015 18:50:44 +0100
Allan Day <allanpday gmail com> wrote:

> Hi all,
>
> I recently started looking at a few issues with the documentation from
> a design perspective. There were a few initial goals for this:
>
>  1. Investigate merging the Getting Started documentation into
> gnome-user-docs, in order to avoid duplication of material.

We've discussed this a few times before and the reasons why these two
modules are separate still apply. The most important factor here is the
module size. Video files are big and the module / package gets even bigger
with every new translation. By having two separate modules, we are giving
distributors a choice not to ship additional ~120M of data on their
installation media, eg.

Also, I don't think there is any duplication of content. For the user, it's
really hard to say whether these two documents are technically separated
into two modules or not. We use cross-references to ensure the
getting-started topics provide links to the user-docs content that goes
into more details. And I think that works just fine.

Besides that, getting-started is a nice proof-of-concept of some of the
killer features of Mallard, like modularity or automatic links. :)

>  2. Update the "home screen" designs. I've become dissatisfied with
> the latest mockups [1] I did for this, primarily because they don't
> give you direct links into content items - this increases the number
> of navigation steps, and doesn't draw the user in as it should.

Well, this is tricky. You can either provide a list of direct links to very
basic topics like we do in getting-started, or you can provide a more
comprehensive list with a broader scope, but that means you have to
sacrifice something. Mallard is however really good at making the
navigation structure easy to use even if your help contains a lot of
different topics covering a lot of different areas.

> As I did research for these tasks, I started to compile a list of
> goals and principles [2]. These are intended to apply to both the
> design of Yelp and gnome-user-docs (some goals apply to both). I'm
> interested in using them as the basis for the two tasks I mentioned
> above (although they could be useful elsewhere).

I like the principles, in general.  I think they can be applied to the
help content provided in all GNOME modules.

Cheers,
pk