ESP Style Guide

This page describes how to write clear and accessible portal pages. It assumes that you know how to use Emacs and ESP and are familiar with the basics of HTML.

Readership

Who are you writing for? Target your style and content to a particular readership (not "the general public"!) but bear in mind that anyone with an internet connection can access your site. Are you expecting that entry-level undergraduates, research students, fellow-specialists, university teachers, for instance will be using the site? It is useful to address both students and teachers, perhaps with a separate section with suggestions for lectures, reading classes, project work, essays, etc.

However, because of the internet's inherent accessibility, you must also bear in mind that many unexpected people will also find your site. They may not read English well, and almost certainly will not know as much about your subject as your target readers. Try to limit your use of jargon and use the People, Gods, Places and Technical Terms lists, along with other supports (maps, timelines, etc.) to make your work as accessible as possible.

The following suggestions are also aimed at increasing the readability of your ESP site.

Page names and naming conventions

Use the following naming conventions to keep the site navigation simple and to prevent errors during site rebuilds:

The page name is given by <esp:name>. Keep this short and meaningful as it will appear in the navigation menu and also becomes the page URL.
The page title is given by <esp:title>. This text can be much longer than that given in <esp:name>.
Links to internal pages should use the short page id defined in the <struct:page> tag in structure.xml. See the documentation on internal links.
Use lowercase only for all file names (e.g. assurnasirpals-palace.xml) and short page ids (e.g. <esp: link page="assurnasirpals-palace">). Do not use spaces, as this will cause errors during site rebuild. Instead, separate words with an underscore or a hyphen (i.e. BM-92668.jpg and not BM 92668.jpg).
Do not use any special characters (ṣ, š, etc.) within <esp:name> as they will not display as part of a URL. Special characters are fine to use within <esp:title> though.

Organising principles

Upper-level pages

Think hierarchically, not linearly when planning website structure: introductory pages to sections should give an overview of the whole section. Using <dl> lists can be useful for this, with the <dt> serving as a link to the subpage and the <dd> containing a short description of what the reader will find there.

Lower-level pages

However, search engines allow visitors to enter websites on any page. Make sure that each page contains enough contextual information to work as a self-contained entity. Ensure that all sub-pages have a prominent link early on in the text to the appropriate introductory page.

First paragraphs

On the same principle, first paragraphs should give overviews of the whole page, with seamless in-text links to what comes next. Tag first paragraphs as <p class="firstpara">.

Headings

Include a short and enticing heading for each paragraph or section. This help your reader to navigate around the page and encourage them to read on.

Page menus

If the page is particularly long, add a short menu of page headings immediately after the first paragraph, perhaps like this:

<p> <esp:link bookmark="h_thing1">Thing 1</esp:link> | <esp:link bookmark="h_thing2">
Thing 2</esp:link> | etc.</p>

Paragraph structure

Think about what users need to know and when. Paragraphs should be short, and longer quotes should be blocked using <blockquote>. Think about how pages end too.

Sentences

Above all, keep your sentences short and simple. Avoid the passive voice whenever possible, and try to write in a lively and accessible style.

Images

Do not start a page with an image; the checker will flag this as an error.

Images and their captions should tell a story, preferably complementary to material in the main text. Don't refer explicitly to images in the main text, but link to them instead. See more below on selecting images and writing captions.

Glossaries

Compile lists of People, Gods and Places, and of Technical Terms as you go: who, what, when needs further explanation? Write up two-line glossary entries as you go in a separate file, ready to go in the <esp:glossary-list> and <esp:techterms-list>.

Links

You should like to other Oracc pages by following the rules given here. You must link to other web pages by using full URLs, not the short forms ("tiny URLs") offered by services such as tiny.cc.

Selecting images and writing captions

The Knowledge and Power [http://oracc.museum.upenn.edu/saao/knpp/] and Nimrud [http://oracc.museum.upenn.edu/nimrud/] sites use 9cm width as their standard image size. Know the standard image size chosen by your project and consider how each image will look at this size. Don't use tiny versions of very detailed images; instead consider whether a cropped section is more appropriate and eye-catching. To provide the full amount of detail, create a link to a larger version of the image.

Image captions should stand independently from other text on the page and ideally tell a complementary story. Remember that users may choose not to read the main text first (or at all!).

Images of museum objects should ALWAYS be captioned to include the museum name and accession number.

Images sourced externally, e.g. from another museum's website, should be linked back to the source. Provide a link in the image caption (and also consider making the standard image into a link). Include any external credit line (with link to external credits/licensing page) as appropriate.

Make image file-names consistent and sensible. For images of museum objects, for example, use the museum accession number and name, such as BM-92668.jpg rather than some-random-name.jpg. Consistent naming is beneficial for site maintenance and for answering image queries from end-users.

For more technical instructions, see the page on images in ESP.

Bibliography

There are three methods to create a list of materials suggested for further reading, based on the functionality required. Each project should choose which method to use, and stick to it consistently.

One centralised bibliography: If you want your readers to have access to a single bibliography (as in the back of a book), use links to a bookmarked bibliography.
Footnote lists: If you want to create footnoted references (as in the bottom of a book page), use the referents.xml file
Self-contained reference lists: If you do not want a single bibliography, but instead want to create self-contained reference lists on individual pages (as in chapter bibliographies), use the referents.xml file.

For more information, see the help page on referencing in ESP.

Whichever method you choose, use full citation formats (such as given by the Chicago Manual of Style's Quick Guide [http://www.chicagomanualofstyle.org/tools_citationguide.html]). Consistent formatting is essential so as not to confuse your readers, and to adhere to normal academic standards.

Don't use journal abbreviations, etc. because your readers won't necessarily know what they mean. Add links where possible to online editions/publications.