lists vs procedures WAS: Patch for Kubuntu Desktop Guide: Games Section

Matthew East mdke at ubuntu.com
Wed Feb 15 07:41:06 UTC 2006


Brian Burger <blurdesign <at> gmail.com> writes:

> 
> On 2/14/06, Jeff Schering <jeffschering <at> gmail.com> wrote:
> > On 2/14/06, Brian Burger <blurdesign <at> gmail.com> wrote:
> > > Actually, in the Ubuntu Desktop Guide, we/I replaced the qandasets
> > > with sectX tags (sect1, sect2, etc), and mdke has been replacing our
> > > orderedlists with itemizedlists (going from numbered lists to just
> > > bullet points, in other words...)
> > >
> > Procedures such as those found in the common tasks section of the
> > desktop starter guide need to be numbered. Bulleted lists are not used
> > in procedure steps, and only when the order of list items is not
> > important.
> >
> > Both the orderedlist tag and the itemizedlist tags are not the correct
> > tags for procedure steps. Instead, we should be using the procedure
> > tag. See  http://www.docbook.org/tdg/en/html/procedure.html and also,
> > from the KDE Docbook Authors Guide:
> > http://i18n.kde.org/doc/markup/lists.html
> 
> Thanks, Jeff. I'm still learning DocBook/XML by hacking other people's
> code, and the semantic markup of it still trips me up sometimes.
> 
> Links bookmarked, and I'll start changing UDG over later this week.

Actually I think we should look carefully at this. While procedure tags may
technically be the correct tag to apply, I think the output will be totally
rubbish. Using <procedure><title>Example section in guide</title> will produce:

Procedure 1: Example section in guide.

That means that everywhere in the guide we'll have:

Procedure 24: Connecting to the Internet
Procedure 25: Browsing Network Computers
Procedure 26: Email
Procedure 27: World Wide Web

(as an example).

I really think that doing this would be a blow against usability and readability
of the guide. I prefer the bulleted ists because they display better and the
numbered seem to me to make it more difficult to read. However if people prefer
the look of the numbered lists, we can revert to those. I'm really not keen on
having the word "procedure" all over the guide. Tell me if I've misunderstood
how the tag works.

What do others think?

Matt





More information about the ubuntu-doc mailing list