| |
Reinforcement Learning and Artificial
Intelligence (RLAI) |
|
Style guide for authoring open web pages |
To author a page is to
participate in forming its content: to create, edit, refactor, or
extend it.
An open web page is a web
page that can be authored by anyone
with a web browser. It is surprising how well this can work.
If you are permitted to edit an existing page (and typically everyone is) then you are encouraged to do so in any way that is fully consistent with the page's ambition statement. You can even correct errors in the ambition statement, or otherwise clearly improve it, as long as the meaning (ambition) is unchanged. In other words, anything goes as long as you respect the ambition and follow these guidelines. If you want to change the ambition, make an alternate page (with its own ambition statement) and provide a short link to it either at the top or just after the original ambition statement, whichever is clearer for concisely suggesting the new ambition.
Nothing is sacred or privileged or owned by the creator of a page
except its ambition.
Ambition statements are one way to perform the critical and
oft-neglected function of keeping the reader oriented. Remember
that many of your readers will have come to your page from places you
did not anticipate. Tell them plainly what your page is
about.
Define your terms. Make your page understandable largely on its
own. Write out acronyms. If there is some required context or
background, provide
pointers to it.
To encourage collaborative authoring, most open web pages keep to a very simple format, like this one,
without animations, graphics, advertisements, or links to
superficially related things. They emphasize interesting and
substantive content over superficial
appearance. Maybe it need not be so, but there tends to be an
inverse relationship between the flashiness of a web site and the
quality of the ideas presented in it. We seek pages that are easy
to create and change by thoughtful people, none of which is encouraged
by complex page formats.
We honor the humble paragraph.
After discussion and brainstorming on a page has died down for a while, it is expected and encouraged and understood that its content will be mercilessly edited (refactored). Content that makes poor reading, or that otherwise seems not to contribute to the ambition, will be removed, or moved to a descendant page with a link. Questions asked will be put together with their answers. Misunderstandings will be corrected before they are even seen to happen (this might be a good reason for editing the ambition statement). Another polite thing to do when you delete someone else's content is to email it to them so that they can find a better place for it. Even more polite would be to find that better place and move it there (and send the author email).
Given this practice, the best way to contribute in a
lasting way to write something that 1) communicates clearly, 2) is
relevant to the pages ambition, 3) is no longer than it has to
be, and 4) respects the views of other authors.
An open web page may have many authors (and no owners) but
nevertheless tends to have one or a few that take responsibility for
it. It is extremely helpful to a web page to have authors that take
responsibility for it. To encourage people (read you) to take
responsibility, their contribution should be recognized. If you
create a page or actively maintain its content, please indicate your authorship in some way.
One way to sign your web page unobtrusively is with a signature mouseover,
a small graphic that shows an author and time stamp when the mouse
cursor is allowed to rest on it for a moment. Try it with the
mouseovers near the top of this page (they look like this ).
You must have "show tooltips" turned on in your browser settings for
this to work. The first mouseover on a page often indicates the
author of the page's ambition statement.
If you extend a page, a signature mouseover will be automatically generated and added to it (using whatever name, if any, you provided with the extension text). If you make changes with an editor, you can grab an existing mouseover from any page, drag a copy to the page you are editing, and then alter it with the editor to show the appropriate information for your changes (in Mozilla's editor you double-click on the mouseover).
Open web pages that are hosted by the RLAI group at the University of Alberta
by default have the RLAI logo in the upper left corner. You can delete this logo
if you like (these pages are open; you have control). You should also feel free to delete or change the
"Reinforcement Learning and Artif..." in gray across the top.