implementing TopicBasedHelp

[Matthew East]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

* Richard Johnson:
> On Sunday 03 December 2006 07:49, Matthew East wrote:
>> First, inter-linking. I think the best way to do this is simply to use
>> normal <link> or <ulink> tags to link to another document. Since this
>> isn't easy to do with the current translation structure we use
>> (documentname/language/documentname.xml), I think we will have to switch
>> to (language/documentname/documentname.xml). This means that relevant
>> links should work for all languages without having to do any tweaking or
>> substitution or anything.
> 
> A note for Kubuntu interlinking. When you link to another document that is in 
> help already, <ulink url="help:kubuntu/about_kubuntu">About Kubuntu</ulink>. 
> An easy way to see which links to add, go into KHelpCenter and mouse over a 
> link in the main window. It will display the link in the bottom bar.

Unsurprisingly, the Gnome help browser has this feature as well, but I
explicitly avoided suggesting it, for two reasons. First, which is
irrelevant to Kubuntu, it requires installing the documents in
/usr/share/gnome/help/, whereas we've traditionally installed them in
/usr/share/ubuntu-docs. But more importantly, in order to retain
DE-neutrality. That way, material which is copied from Ubuntu to
Kubuntu, or vice versa, we don't have to go around changing all the links.

>> A number of what used to be chapters of the desktopguide are likely to
>> become single documents. I've fixed up a couple of these to show how that
>> might work (add-applications and games), and the others are not yet fixed
>> up. I've made a note of which ones aren't working in the appropriate
>> directory.
>>
>> Does anyone have any comments on this sort of directory structure? It's a
>> bit difficult to predict what problems it might cause, so I'd love some
>> feedback.
> 
> With the Edubuntu handbook, I broke each chapter into a seperate file. The 
> best thing about this is it is easier to task out each chapter. This way here 
> you can work on a chapter and not have to worry about someone else needing to 
> work on it as well. So breaking down either each topic into a file, or break 
> each topic down into subtopic files will work as well.

Erm. All our substantial documents (desktop guide, server guide and so
on) have done this for the last 2 or 3 releases... I'm not quite sure
where you're going with this.

Matt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFcwmptSaF0w5rBv8RAlMeAJ9ZdrDZ4TJPcHfFVauU17cRR2I+KQCfZgg7
lSuSvs0KoaWyvtTVYhMCAxQ=
=7kMH
-----END PGP SIGNATURE-----