Writing for Hypertext Bible Commentary

Introduction

How the commentaries are organized

The aims of the commentary

From Overview to Detail

Book level comment

Comment on the major sections

Detail

Explanation and Justification

Bible Dictionary material

How electronic hypertext and print differ

Thinking links

Scanning not Reading

Enabling reading not leading readers

Technical details

Styleguide

Signaling links

Justification and explanation

Internal links and anchors

Hypertext Bible Dictionary articles

Bible references

Styles and how to use them

How NOT to format

Tabs, tables and spaces

Fonts

 

0.  Introduction

Hypertext is text that is linked. A hypertext is formed from an interlinked collection of small textual units. These chunks of text are called lexia. In practice they are usually stored as separate files. Lexia are joined by hyperlinks. This encourages readers to follow different paths through the material. Thus usually any particular lexia may be reached by more than one (often many different) routes. Therefore each lexia must either be able to stand alone, or must contain links to the material that enables readers to understand it.

This difference poses some problems of adjustment to scholars operating with a codex (or even scroll) [1] as their mental "map" of the nature of text. Instead it is helpful to remember that each lexia stands alone, yet at the same time works collaboratively with others (see "Thinking links").

This is inconvenient for a document - like a monograph [2] or this manual - that seeks to lead the reader to particular conclusions or results. By contrast it is most convenient if the aim is to equip the reader, e.g. in a commentary that seeks to equip its readers to read the original text for themselves.

This manual begins with a section on the practicalities of how material for a commentary in the series is organized (section 1). A brief discussion of how text and hypertext differ, leads to suggestions about the rhetoric and style of writing hypertext material (section 2). Technical details of "how to" prepare material for publication in the HBC_ are dealt with last (section 3).

1.  How the commentaries are organized

The prototype Amos "volume" required numerous articles of the sort found in Bible Dictionaries, and mini word studies for the vocabulary used in the book. However, we hope that the Hypertext Bible Dictionary articles will cover most of the need for such articles and will try to get funding for research assistants to prepare the mini-word studies. So this section of the manual will focus on the comment on the biblical text, rather than including also this ancillary material. 

1.1. The aims of the commentary

HBC_ aims to equip readers to read/interpret the text. To this end comment should try to provide useful and relevant information about the text and its contexts. The intention is to offer a level of comment that goes beyond what the reader can work out for themselves using Bible software, but to avoid "pushing" one particular interpretative line.

The aim is to provide a similar level of comment to a multi-volume print series. So beginning readers will need technical terms and ideas explained, while biblical scholars will want a justification for a conclusion reached. Thus as well as the basic commentary material two other sorts of lexia will often be needed (for how to handle these different needs see Explanation and justification).

The system will allow readers to seek Bible Dictionary articles for themselves, but sometimes you may want to provide a link in your text to a particular article. Thus you should (usually) not include description of people, locations or widely used concepts (e.g. "Onesimus", "Megiddo", "Kingdom of God") except where some particular detail (not covered in the HBD entry for that term) is needed for your commentary, rather you should link to the entry. (See Signaling links.)

1.2. From Overview to Detail

The commentaries will be organized at more than one level. Most often there will be three levels:

A really short book (like 3 John or Obadiah) might be handled differently with only one or two "layers" of comment. Authors preparing comment on longer books (like Isaiah or Revelation) may need to add another level. Please discuss such needs with the editors.

At each level lexia should start with a list of the units treated at the next level (which can be links, in case your reader was looking for more detailed comment).

1.2.1.  Book level comment

This comprises one basic lexia with as many sub lexia (for explanation or justification) as are needed. It should discuss such topics as:

In general this material is likely to be less comprehensive than in a conventional commentary, since some of the traditional material included in the "Introduction" may be linked from lower level lexia.

1.2.2.  Comment on the major sections

These lexia are likely to be among the longer units you will write, but should not become too long (be alert for occasions when you should prepare a separate [linked] lexia with some of the material). In this lexia you are likely to describe:

1.2.3.  Detail

The lowest level should deal with a single unit. It is likely to treat questions of genre, rhetorical purpose, imagery etc. the list of headings will differ according to the genre of the text, and the commentator's interests! This is one case where internal links should definitely be used, so that discussion of the elements (e.g. of the wording) can be included under a subheading (e.g. the verse number).

General comment can be organized under headings, it is convenient for readers if (where possible) you use the same list of headings each time (just omitting those not needed). Those I used most often for Amos were:

1.3. Explanation and Justification (see also the "how to" section)

Apart from links to Bible Dictionary articles (whether from the Hypertext Bible Dictionary or written specially for your commentary [3] ) there are two main types of lexia to which the material you write will link:

·  explanations provide readers who lack technical knowledge with the means to understand what you write

·  justifications allow readers who are interested to see the reasoning and evidence that supports a conclusion that you simply stated in the lexia you were writing

When signaling a link to another lexia you should identify it as one or the other of these categories. Bible Dictionary entries will provide a third category of link. Users will be able to tell in advance which sort of material a link leads towards, e.g. by a tooltip [4] that reads "explanation" or "justification" or "Bible Dictionary".

Almost always explanations are aimed at lay or beginning students, while justifications are more likely to be sought by "experts".

Because you are writing more tersely than for print (see below), as you write you should be thinking about where you need to supply such "explanation" or "justification" lexia. I suggest that you make a new file for these required lexia with a heading and brief reminder of the purpose and note from where the link comes so that later you do not overlook providing this material. ("Explanation" lexia may often be used from more than one location in your commentary, while "justifications" are more likely to refer to one particular locus.)

1.4. Bible Dictionary material

Much of the necessary background information can be found in existing or expected future Hypertext Bible Dictionary articles (see the list or in articles written at our request) [5] – if so you can link to them. Some more specialized information you will need to supply yourself as an "explanation" (or possibly "justification") lexia.

The HBD is a separate project, but we have the right to use its articles, and are represented on the editorial panel. Articles will usually be around 1,500 words, we expect the first 100 entries to be complete in 2006. Authors are being recruited upon recommendation, and all entries will be approved following a peer review process.

The Hypertext Bible Dictionary (HBD) is a general reference work that makes biblical scholarship accessible online to undergraduate students and general readers. The resource offers original articles on books in the Hebrew Bible, Apocrypha, and New Testament, and on individuals, groups, artifacts, locations, events, and institutions. Articles are concise (no more than 1500 words in length, excluding bibliography); authoritative (subject to peer review and periodic revision); academic (descriptive and historical, not prescriptive and confessional); and introductory (giving an overview and recommending further reading). [6]

2.  How electronic hypertext and print differ

A text is one continuous sequential series of sentences organized into paragraphs and other higher-level clusters. A hypertext comprises a number of short discrete texts that are interlinked in complex non-linear ways. An electronic hypertext is read on-screen. These two differences (linked chunks vs. sequence, and screen vs. print) make writing effectively for the two media very different.

2.1. Thinking links

Since hypertext is composed of linked lexia, and since readers may have reached any lexia by several (or even very many) different routes, each lexia should stand alone. So (to help you avoid overlooking material you planned to write) compose each lexia as a separate document. As you edit your material, do not always read the lexia in the same order, so you will be more likely to spot where explanation links are needed.

Each lexia should be relatively short and focused. A couple of hundred words is a good length, often if you get beyond this length you could think of splitting the unit in two parts! When writing hypertext, within reason, fragmentation is good since it enhances focus. In a text coherence and structure are vital, however focus is vital in a single lexia (written to work as part of a hypertext).

As you read over what you have written think about what beginners will need explained. Either build in a link to an existing explanation (Bible Dictionary article or lexia you have already written) or make a blank document with a heading that reminds you to write the required lexia. E.g. if the reader needs some summary introduction to "Prophets in the Mari texts" then make a document with this heading, and a brief note to yourself about why it is needed. This way later you can prepare the required lexia, and can build in the necessary link as you are still writing the first lexia.

Similarly where colleagues or other readers may want to know your evidence or reasons create a document and link to it (as "justification") even if it only has a title at this stage.

2.2. Scanning not Reading

Readers of text on screen have been shown not to "read" sequentially, but rather to scan pages for information. [7] When writing for this medium it is helpful to bear this tendency in mind and adapt one's style accordingly. Features that have been shown to promote comprehension include:

The best advice from practitioners of writing for screen, as well as empirical studies like Neilsen and Morkes, suggest that as academics we need to reverse our usual writing "logic". Traditionally we write towards a conclusion. Readers onscreen expect to work outwards from a summary. This is called a "reverse pyramid" – writing towards a conclusion focuses down towards the end, the reverse pyramid puts what is most significant first.

Traditionally, people scan English language documents by reading the first few words of each paragraph. For this reason, put only one idea in each paragraph. And put the main idea right up front, in the first few words…. Never tease people and force them to guess your point. [8]

2.3. Enabling reading not leading readers

The role of commentary is to describe and explain the text. Comment seeks to assist its reader to understand and make sense of the text. To this end difficulties and puzzles in the text are exposed, described and explained, context is explained… However, traditional commentary is driven by the sequential print format to lead the reader towards sharing the commentator's interpretation of the text.

Hypertext, with its links and varied paths is more conducive to allowing its users to explore aspects of the text that interest them. Thus, although a hypertext commentator can present their "way of reading the book", it is less easy for them to insist on this way of reading. By contrast the form facilitates offering the user other "ways of reading" also. This openness is a feature of the medium that we are keen to exploit, so authors are asked to present not only their own reading of the text, but also to explore and present material that might be useful or interesting for other readings.

Sectarian reading of the Bible is common (not only religiously sectarian but also "secular sectarian readings" e.g. those that deny the possibility of supernatural events described in the text). Such sectarian readings may be presented, but where possible authors should identify them as such using phrases like "a Christian reader might understand…", and where possible more than one such reading should be presented. E.g. when commenting on Isaiah 9, New Testament use of the passage to refer to Jesus should not be overlooked, but nor should it be the only understanding presented. 

3.  Technical details

Wordprocessors: allthough text for HBC_ could be prepared in either Open Office or MS Word (by special arrangement) it will make the editorial process much easier if you use an HTML editor. We have prepared instructions for using KompoZer Portable a small editor which works very much like a wordprocessor without allowing too many options that you ought not to be using (like the footnote feature or Tab key).

Templates: If you are using KompoZer please use the supplied Template, hbc_ template.mzt to create new files. Please make no changes made to the Styles in the Template. If you are using another HTML editor then please attach the stylesheet main.css to each file.

Characters from non-Roman alphabets and other special characters should be standard Unicode. The writing system should be indicated using the "class" styles "Hebrew" or "Greek" from the supplied Template.

3.1. Styleguide

This is a longer quotation in the Style "Quotation" the words quoted should be followed by a reference in brackets, either a Bible reference in SBL style or to the work cited. E.g. (Am 3:12) or (Blogs, 63)

3.2. Signaling links

Authors should aim to indicate where links are needed or may be created. There are two methods of doing this. The approach outlined here is easier and cheaper to convert, however if you find this inhibits your editing of the text then simply place the indications of links as comments, with the highlighted words forming the link text.

3.2.1.  Justification and explanation

Where you create "justification" or "explanation" lexia you should think about how, and from where, these lexia will be accessed. Links are normally made from sections of text (usually just one or a few words long), which themselves suggest or at least hint at the linked material. Such links should be made in KompoZer and then marked with the appropriate class either justification or explanation.

3.2.2.  Internal links and anchors

It may sometimes – most often where a longer lexia needs a list of headings at the start, for example linking to verse level comment within comment on a unit  – be necessary to link to a location within a lexia. These may be made using the anchor and link tools (see Using KompoZer).

3.2.3.  Hypertext Bible Dictionary articles

Often it will be useful (think particularly of untrained readers) to link to a Bible Dictionary article.

Where such an article exists in the HBD, or where such an article is listed as desirable, if possible make the link text in your lexia the same as the head word (or term) of the dictionary entry mark. In any case in the link location box type the exact term e.g. the HBD article is titled "kingdom of God" not "God, kingdom of" or "kingdom of heaven", so putting "kingdom of God" in the location box will link to the article headed "kingdom of God" even if your linked text read "kingdom of heaven".

If no such article is yet listed, but where you think one would be desirable add double asterisks round the title to indicate this to the editor e.g. "**Ugaritic mythology**"

Where either you do not think it likely that the HBD will need to include an article, or you prefer to create your own, make the link as a standard "explanation" (see above).

3.2.4.  Bible references

You should take care that Bible references are given in standard (SBL) abbreviated format with the book name included (e.g. Is 5:3). If you make a reference in another format e.g. "in verse 16" then you should mark it as a link with asterisks and the mention [Bible reference] thus: "later in the chapter (**v.13 [Bible Is 5:13]**)" will read "later in the chapter (v.13)" where v.13 is a link to Isaiah 5:13. If you need to make reference to a particular translation you should usually quote the text directly.

3.3. How NOT to format

As we have seen above, with VERY few exceptions NO styling should be used that is not applied as either a "paragraph" or a "class" Style.

3.3.1.  Tabs, tables and spaces

3.3.2.  Fonts

Do NOT use fonts at all. They should ALWAYS be assigned by the Style chosen.



[1] As I discovered when I began the Amos prototype, and found that the ease with which onscreen text can be scrolled tempted me initially to write long documents with many internal links! Some traces of this phase of writing Amos can still be detected in the published Amos: Hypertext Bible Commentary. E.g. Tim Bulkeley, "GENRE: Kinds of Literature”, Amos: Hypertext Bible Commentary, Auckland: Hypertext Bible, 2005.

[2] See Tim Bulkeley, "Form, Medium and Function: The Rhetorics and Poetics of Text and Hypertext in Humanities Publishing", International Journal of the Book 1, 2003, 317-327

[3] When you need an article that does not (currently) exist in the HBD, either we can commission such an article or you can prepare one, these options should be discussed with the editors.

[4] "Tooltips" are small boxes that appear when the user's mouse hovers over a link or other focus of potential action ("tool") telling the user the result of using the "tool".

[5] That is, if you think that the current list misses a topic that should be covered in the HBD we can commission an article. If however you need an article with a particular slant or emphasis, or the article is likely only to be needed by your commentary, then you should provide the entry yourself as a lexia.

[6] Cited from the draft "Instructions for contributors” being prepared for the HBD project.

[7] John Morkes and Jakob Nielsen "Concise, SCANNABLE, and Objective: How to Write for the Web"  http://www.useit.com/alertbox/writing.html (downloaded 30/06/00)

[8] R. McAlpine, Web Word Wizardry, Wellington: Corporate Communications, 1999. 98.

[9] Patrick H. Alexander, et al. (eds.) The SBL Handbook of Style: For Ancient Near Eastern, Biblical, and Early Christian Studies (Peabody, Mass.: Hendricksen,1999)

[10] If such a style is needed and does not already exist contact the editors and one will be added to the Template.