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.
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.
Use the following naming conventions to keep the site navigation simple and to prevent errors during site rebuilds:
<esp:name>. Keep this short and meaningful as it will appear in the navigation menu and also becomes the page URL.
<esp:title>. This text can be much longer than that given in
structure.xml. See the documentation on internal links.
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.
<esp:name>as they will not display as part of a URL. Special characters are fine to use within
<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.
<p> <esp:link bookmark="h_thing1">Thing 1</esp:link> | <esp:link bookmark="h_thing2"> Thing 2</esp:link> | etc.</p>
<blockquote>. Think about how pages end too.
The Knowledge and Power and 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.
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.
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). 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.
Here are some useful pages about academic writing for the web, but there are also many others:
Your university probably has useful guides and/or tutorials too; ask around.23 Jul 2014
Eleanor Robson & Ruth Horry
Eleanor Robson & Ruth Horry, 'ESP Style Guide', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2014 [http://oracc.museum.upenn.edu/doc/help/portals/styleguide/]