Re: Mallard 1.2 Ideas

[Shaun McCance <shaunm gnome org>]

On Wed, 2009-08-05 at 17:11 +0100, Phil Bull wrote:
> Hi Shaun,
> 
> On Mon, 2009-08-03 at 19:39 -0500, Shaun McCance wrote:
> [...]
> > I'm planning to add root links or index links (I haven't
> > decided on the name yet) that allow you to set additional
> > pages as being a root for some page.
> 
> I think that this could get too complicated and might result in people
> getting lost in the docs. If I go down six levels in the user guide and
> then the root suddenly changes to "Nautilus" in the breadcrumb bar, it
> might not be obvious how to get back to the user guide. Have I
> understood the feature correctly?

That's a valid concern.  But without this feature, we'd get
no link trails at all on those pages.  We have to cap the
link trail length at some point, and larger documents are
inevitably going to nest more deeply.

What if we always inserted the real root to the left of
the specified root, maybe with some indication that we're
skipping some levels?

Help >> ... >> Nautilus >> Rename files and folders

I'm just thinking out loud here.  Perhaps it's best to take
a "wait and see" approach until we see how things shake out
with larger documents.

> > So imagine you have a page telling you how to do something
> > in Nautilus.  Taken in the context of the User Guide, maybe
> > this page takes six steps to get back up to the root.  As a
> > result, no link trails are shown, because the link trail is
> > too long.
> 
> > But if we have a page that we could consider to be a landing
> > page for all things Nautilus, we could set that as an extra
> > root for all Nautilus-related pages.  Then those pages would
> > get link trails that would at least get you back up to that
> > Nautilus guide page, if not the index page.
> 
> Given that we now have Mallard's awesome linking capabilities, should we
> still be thinking in terms of a User Guide? Why don't we write
> documentation on a per-application basis (i.e. nautilus docs are kept
> with nautilus code) and use DITA-like maps (or something similar) to
> pull appropriate sections from different modules into something that we
> call the user guide? When a certain element doesn't make sense in one
> document but must be present in another, we could use conditional
> processing (maybe from within a map?) to discard or include the element
> as appropriate.

All right, let's kill the term "User Guide" right now.  Let's
talk about the "Desktop Help".  The Desktop Help is a document,
and it will be the default document loaded by Yelp.  It has
lots and lots of pages that deal with various things.

The Nautilus Help is a collection of pages all about Nautilus.
I'll call any collection of pages a "stack".  As I've said
before, I think it makes sense to maintain certain stacks in
separate modules.  So the Nautilus stack would be maintained
in the nautilus module.

But we'd install the Nautilus stack into the Desktop Help
document.  To the user, it would appear as if the Nautilus
Help is just a part of the Desktop Help.  We wouldn't do
this with all application stacks.  The Empathy stack will
just be a separate Empathy document.

Link trails always stay within a document.  So once we put
the Nautilus stack into the Desktop Help, Yelp will try to
construct link trails on Nautilus pages that link all the
way back to the Desktop Help index.page file.  This all
fits into Mallard's goal of taking pages from disparate
sources and turning them into a single coherent document.

So in a sense, what this proposal is about is allowing us
to specify sort of subdocuments within a document.

--
Shaun