use of alerts on the help wiki

[Matthew East]

Hiya

On Sun, Sep 21, 2008 at 11:58 AM, Andrew Sayers
<andrew-ubuntu-doc at pileofstuff.org> wrote:
> Matthew East wrote:
>> Do you feel strongly about this point?
>
> Well if you're saying the evidence is that it's less usable, then that's
> got to take precedent.  That said, here's my position:
>
> I'm talking to you now because I saw people creating alerts manually,
> then tried to make a better one, then decided it was a problem that was
> better automated, thought to mention it as an aside to another e-mail,
> happened to notice that macros exist and aren't hard, and so on.  My
> concern is that projects only get contributors if they provide every one
> of those stepping stones.

I definitely think whichever solution we adopt, the problem you saw
will be solved and that your macro will be very useful to ensure
consistency throughout the wiki pages. So I'm grateful to you for
going ahead and scratching this itch, which will certainly benefit the
wiki generally.

> I'm still not sure I understand the problem - is it an issue of typos or
> confusion?

It's both really. Although I think that either solution would be an
improvement, I think the simple one is best placed to ensure
consistency and ease of use. It's easier to remember, and it's simpler
to give contributors a choice of three easy macros which in my opinion
fit all the possible use cases for alerts. They also match the ones we
actually use for the system documentation, which is an advantage.

(Well, actually there are five available for the system documentation
- http://doc.ubuntu.com/ubuntu/libs/admon/ - but "warning" and
"caution" overlap, and so do "important" and "note" - we generally
only use three. As Phil pointed out, Gnome also recommend three -
http://library.gnome.org/devel/gdp-style-guide/2.23/infodesign-18.html.en)

>  It would be trivial to create a <<Hint(foo)>> macro that
> runs <<Alert(Hint: foo)>> internally, which would give us both
> interfaces - would that be any better?

I think that might increase the confusion a little bit. It depends on
how we document them, I suppose.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF