use of alerts on the help wiki

[Andrew Sayers]

Hi Matthew,

<snip - Andrew sounding like a prima donna>

Re-reading that, I came across kinda wrong there.  Let's just strike it
up to another lesson in not e-mailing when you're in a hurry :)

What I was trying to say is that, as a standing rule, I like to build
"tweak me!" knobs into projects, to encourage people to get involved.  A
salient (but unextraordinary) example is that it was mainly luck a week
ago that I didn't think "there's no alert thingy, that's a shame... oh
well, never mind", and leave it at that.  As I say, I agree it's more
important to have a learnable system in the simple case, I just need to
work through all the options before accepting there's no way to have my
cake and eat it.

For the record, I don't think anyone could accuse me of letting go of a
problem too easily once I've sunk my teeth into it - and by way of
proof, here's another implementation.  I suspect this will be the last
implementation I need to write - it fixes what I guess is your bug and
includes a generic Alert macro that can be disabled by renaming the file
to Alert.py.disabled.  I'll open up a Bazaar branch if more revisions
are needed, to avoid further spamming the list with tarballs.

The code for the Alert macro was already written, so I figured it's
better to have and not need than need and not have.  Plus, it'll be
quite handy in the next paragraph.

This implementation moves all the tweakable things over to Note.py,
including a few new ones.  In particular, changing "True" to "False" on
line 22 tells the program to use the five doc.ubuntu icons instead of
the three help.ubuntu ones - I think that using the same icons on both
sites will make life easier for readers, authors and maintainers.  I
haven't included 'Important' and 'Caution' macros because of the
confusion issues you cited, but once you've changed the icon set, you
can use <<Alert(caution: ...)>> to try them out, and create a Caution.py
based on the existing Warning.py if you want to include them.

<snip - why not have both?>
> I think that might increase the confusion a little bit. It depends on
> how we document them, I suppose.

Fair enough - how about leave <<Alert()>> out for now, write a
HelpOnAlerts page, edit alerts into a handful of pages, then think
again?  Maybe we'll prove that three alerts cover the entire problem
space, maybe we'll decide that every page needs its own alert type.

	- Andrew
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Alerts.tar.bz2
Type: application/x-bzip
Size: 1978 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20080922/78a210b4/attachment.bin>