Re: Mallard 1.2 Ideas

[Phil Bull <philbull gmail com>]

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?

> 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.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/people/philbull