Patch for Ubuntu Desktop Guide (Re: Words to avoid?)

[Matthew Paul Thomas]

On Sun, 2006-07-09 at 11:05 +0100, Matthew East wrote:
> ...
> * Matthew Paul Thomas:
> ...
> > <http://doc.ubuntu.com/~laserjock/diff-udg-1>
> 
> Thanks a lot for this patch. I've been through it, and it has loads of
> good stuff. I'd like to apply it, aside from a couple of things, but it
> results in some seriously invalid docbook... Use the validate.sh script
> in our repo to check desktopguide.xml, and see if you can fix some of that.

Hmm, apparently <step> and <listitem> require <para> inside, even when
they're not paragraphs. All fixed.

> Here are the things I didn't like in the patch, and if possible I'd like
> you to revert:
> 
> As discussed on irc, as it is now the desktop guide is a book, and so
> the following changes I think are inappropriate:
>  * Removing the introductory paragraph from each chapter explaining what
> the chapter does.
>  * Removing much of the preface.

Done, except for the sections that already have a useful introductory
paragraph.

What should I edit if I want to improve the help that is displayed
on-screen, for which the preface and the "This chapter/section"
paragraphs are very inappropriate? Should I make a copy of the Desktop
Guide and work from there?

> I generally approved of the sections where you removed things from
> procedures because they weren't procedures, but in two cases I think
> that you removed things that _were_ part of procedures:
>  * Menu editing - opening alacarte is part of that procedure

There are three sets of instructions on that page: one for adding an
entry, one for moving an entry, and one for removing an entry. How to
open the menu editor could be the first step in all of those, but that
would be redundant (and confusing if you were making multiple changes).
That's why I put it in the introductory paragraph instead.

I've clarified this by shortening the first set of instructions to a
single paragraph, like the other two.

>  * Setting up 3d rendering on an ATI card - all those steps are part of
> the procedure
> ...

Fixed.

-- 
Matthew Paul Thomas
http://mpt.net.nz/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: diff-udg-2.gz
Type: application/x-gzip
Size: 24958 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20060710/bd68c462/attachment.bin>