[Doc-SIG] Comments on the reST notes

[Garth T Kidd]

> I don't know how Wikis work. When somebody posts a new message I would
> expect it to say "Error in message: please correct" until there are no
> errors, then show the processed version to the user and allow them to
> post or edit their message.

Currently, most Wikis just show you your broken output and let you go
back and edit it if you feel like it and have the time. If not, someone
else will probably fix it for you.

More friendly is to point out the errors, not just show you your broken
output. Many people won't look for a problem unless there's red on the
page.

One step tighter would be to commit the broken input, but also take you
straight back to a page with the warnings and the editor pane so you can
fix it. If you (say) shut down your browser, no problems, your changes
are there and someone can come back and fix it. The key difference is
that you don't have to expend any extra effort to get back to the
editor, thus making it more likely that you'll fix the problem.

One more step tighter is to take the user back to the editor *without*
committing the changes, but supply a button marked "commit anyway and
let someone else clean it up later" just in case they're in a hurry. If
you have to press a button for people to see your changes, you may as
well spend the time to fix the typo, right? :)

Finally; detail oriented sites would change the "commit anyway" button
to something like "leave in edit queue" -- the user can come back and
fix the problems later, or anyone else with queue permissions can, but
users won't see any changes until the syntax is valid.

My personal favourite is the lattermost, but it only makes sense for an
environment with concepts of "user", "queue", and "permissions". None of
the three are considered particularly Wiki, but that's a different
argument.

Regards,
Garth.