Home Reinforcement Learning and Artificial Intelligence (RLAI)
Style guide for authoring open web pages

--Rich Sutton, Sep 12 2004 --Anna Koop
The ambition of this page is to provide essential guidelines for style and etiquette when authoring open web pages. Because open web pages can be changed by anyone, it is important to have common expectations so that different authors don't work at cross purposes. This page seeks to establish such common expectations and to introduce conventions for establishing new common expectations for new open pages. Information on how to author is provided elsewhere.

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.

Ambition statements

An effective way of establishing common expectations about a web page is to start it with an ambition statement, a statement of the intended focus, function and scope of the page.  For example, the page's ambition might be to list all the upcoming conferences related to artificial intelligence, or to be a top-level introduction to the idea of the singularity, with pointers to more information, or to define and discuss the reward hypothesis up to some length and level of detail.  The ambition statement should not repeat the wording of the page's title; a second wording removes ambiguity and will makes the meaning clear to more people.

The ambition stated should be for the current page only, not for the tree of pages below it.  Thus the ambition should be fairly small and circumscribed.

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.

Simple page style ~ Interesting content

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.

The simplest way to author a web page is to extend it, to provide content---humble paragraphs---that will be added to the end of the page.  The recommended page style is sufficiently simple that it possible to create new, perfectly serviceable pages entirely through extensions (this feature is not currently available). Extensions are often later merged and reformed within a page. That is, their individuality may disappear as the page is refactored.


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.

Sign your web page

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).

RLAI logo

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. 

Extend this Page   How to edit   Style   Subscribe   Notify   Suggest   Help   This open web page hosted at the University of Alberta.   Terms of use  6501/2