About Getting Started

Here we document, for the time being, arguments and decisions about the contents, the audience, the writing style etc. of the 'Getting started' document. Here is the outline of the Getting Started Document: Getting Started. Here are comments on the drafts: Getting Started Comments

Purpose

• Someone that has read this document and that has gone through the steps the document describes (installing and using an editor, etc.) should be able to create, modify and validate a simple TEI document. He/she should be able to create an HTML representation of that document. He/she should also be able to assess the hurdles he/she faces in using TEI in his/her project and to decide on a proper course of action (e.g.: undertake project on his/her own, seek help in local institution or in wider TEI community, seek formal training).

Audience

• The document targets an academic (postgraduate, PhD, researcher, professor) that wants to start understanding and using the TEI: e.g. a graduate student who wants to make an edition of a book he/she is writing a thesis on. The document assumes someone working on his/her own, willing to learn something new, ready to work hard and to try various solutions. We assume someone that is reasonably comfortable using computers, but has no experience in programming and no previous knowledge of XML or HTML.
• Secondarily, we should also include in our target audience people who are not themselves scholars but who are, or will be, working as encoders with a project. These may be undergraduates, editorial assistants, etc. We can assume that they are equally motivated with the academic readers, but they may not be familiar with the technical vocabulary of textual studies, bibliography, etc.

Software

• Because we want to help people getting started, there is no way we can avoid talking about specific software programs. We must be specific. Neither can we avoid talking about commercial software, as oXygen is the environment of choice for so many people using TEI.
• We should avoid the editors that are favoured by programmers and other technically oriented persons, such as emacs or vi. We want to minimise the learning effort expended on tools; what people should learn here is the TEI.
• What we also want to avoid are expensive editors. We're writing this for people that are getting started. They are probably unwilling to invest a large amount of money.
• If possible, we should avoid command-line tools. In fact, we want to recommend an editor that comes with validation and facilities for running a transformation.
• We should try to discuss editors that work on the three major platforms.
• The upshot of this is, for me: we discuss oXygen (inexpensive, works everywhere, very powerful, but not open source) and the XML Copy editor (Open source, works on Windows and Linux, reasonably powerful). Arianna suggests including jEdit.
• All of these either come with an xslt processor (oXygen and XML Copy editor) or have a plugin for the purpose (jEdit).
• The 'official' document will be based on oXygen. Other versions will be placed on the TEI wiki.

Schema's and ODD

• From a logical point of view, for any project that uses the TEI, ODD is the starting point. ODD helps you make a schema and the schema helps you create and validate xml documents. From an educational point of view, however, it makes more sense to start with an XML transcription of a document, and introduce the schema after that. A schema, let alone ODD, makes no sense to someone who is not familiar with xml documents. Therefore, the idea of making a schema that fits your documents, and the way of making such a schema, is introduced only after the reader is familiar with modifying and validating XML documents.

Contents

• As to TEI elements, this document stresses elementary things such as div, p, lg, l, hi, etc. As a TEI document must have a header, it will mention the header and provide some instruction for filling it, but it will focus on quickly attaining results, rather that on the administrative side of things.
• As to schema's: throughout the getting started document, we use RELAX NG. We mention DTD's and W3C Schema's as an option, without going into their syntax. We explain RELAX using the XML syntax, and mention the existence of the compact syntax.
• As to XSLT: the document will explain some of the concepts of XSLT (templates, XPATH, ...), and it will encourage readers to make some small changes to a toy stylesheet. It will discuss the stylesheets provided by the TEI and guide readers in making a simple customisation. It will not try to provide further instruction in XSLT.

Style

• We should try to be as clear and simple as possible. In a way, council members are not the best persons to write this document, as they may be too familiar with the technicalities to avoid terminology not immediately clear to beginners. We should be prepared to have this document reviewed by people less experienced in TEI and XML than we are.
• Obviously, divisions of this document authored by non-native speakers of English should be reviewed by native speakers.

Media use

• The document should include lots of screen shots. It may also contains links to video's of screen capture.

Technical setup

• The document is stored in Subversion in SourceForge. The relevant folder is https://tei.svn.sourceforge.net/svnroot/tei/trunk/Documents/GettingStarted. There is a main document (gettingstarted.xml) that includes the separate sections using XInclude. This makes it easier for multiple people to work on the document simultaneously. Editors without SourceForge access can mail updated sections to Peter, who will then add them in SoureForge.
• Sebastian Rahtz has set up a cron job to generate a current HTML view of the source files (assuming they have been committed to the SourceForge repository)
• all sections carry xml:id-attributes. As we should assume new sections will be added or sections will be moved around, top-level sections are identified using two-letter abbreviations.
• names of elements, attributes, etc are tagged using the appropriate elements from the documentation tagset (<att>, <gi>, <ident>)
• images are stored in a subfolder 'images' of the main Subversion folder
• abbreviations and other technical terms refer to entries in the Glossary using <ref> elements
• examples will be numbered by the stylesheet. We provide them with id attributes with values 'xaabbb', where 'x' is a literal, 'aa' is the section id and 'bbb' is an acronym for the example, unique in that section of the document. Refer to the examples using <ptr>