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 | Page names | Organising principles | Images and captions | Bibliography | Readability

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:

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.

More on readability

Here are some useful pages about academic writing for the web, but there are also many others:

For the research behind these guidelines, see for instance Jakob Nielsen's Reading on the web [http://www.useit.com/alertbox/9710a.html], How little do users read? [http://www.useit.com/alertbox/percent-text-read.html] and, most recently, Website Reading: It (Sometimes) Does Happen [http://www.nngroup.com/articles/website-reading/].

Your university probably has useful guides and/or tutorials too; ask around.

23 Jul 2014 osc at oracc dot org

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/]

 
Back to top ^^
 

Released under a Creative Commons Attribution Share-Alike license 3.0, 2014. [http://www.facebook.com/opencuneiform] [http://oracc.blogspot.com] [http://www.twitter.com/oracctivity]
Oracc uses cookies only to collect Google Analytics data. Read more here; see the stats here [http://www.seethestats.com/site/oracc.museum.upenn.edu]; opt out here.

http://oracc.museum.upenn.edu/doc/help/portals/styleguide/