Guidelines Improvement – Suggestion

[thea-m]

Dear all,

I would like to make some suggestions to improve the guidelines, inspired partly by the Epidoc guidelines (http://www.stoa.org/epidoc/gl/latest/). Please tell me what you think about them or add any other suggestions you might have. Technical note: It would be possibe to move the guidelines out of the wiki to a separate page, similar to the bibliography page, so you do not have to limit your thoughts to the possibilities of the wiki.

I would propose the following:

1. Keep the distinction between specific guidelines for works, places and persons, and split the current general guidelines into manuscript specific and actually general markup guidelines.

2. Add a clear and light section for each of these sections explaining the basic structure of the records without crowding it with too many details, possibly also in the form of diagrams: http://www.balisage.net/DocumentModels/BalisageTL/index.html

3. Have more detailed sections for all the entity types with:

   • descriptions of the records following their structure
   • links to TEI for the used elements
   • links to the pages of the used elements and attributes, therefore also:

4. An individual page for all elements and attributes we use, describing their use in all contexts.

5. Up to date examples in all sections and for all mentioned elements.

6. An index, which lists all used elements and attributes and links to their page.

7. Links to at least two complete and reviewed xml records for all guidelines sections as reference for new users

What do you think? Do you have comments or suggestions?

Thank you!

[PietroLiuzzo]

798

[PietroLiuzzo]

you know that you can see the diagrams clicking the graph view in oxygen, isn't it?

[PietroLiuzzo]

I would list all pages and then list all table of contents, the main entry point will point to a list of table of contents and the each of these will provide a different approach to the organization of the contents (and might not include all!). e.g. we could have entity type oriented toc like we have now, but also decoration oriented toc, which would point only to what concerns art historians, for example

[PietroLiuzzo]

examples could be just link to XML view instead of being there statically, or even links to xpath searches which would return the entire list of occurrences of the described phenomenon

[PietroLiuzzo]

we also need general encoding practice sections, to describe for example ref and corresp, bibl, relation

[PietroLiuzzo]

for the ontology documentation this is a very nice example of navigation for the ontology

http://doc.biblissima-condorcet.fr/ontologie/bibma/

[thea-m]

Thank you, @PietroLiuzzo ! I agree with your suggestion for the table of content and general structure (I think what you mean by general encoding sections I had included in the general guidelines, but not formulated clearly). I'm not yet so sure about adding the examples as links, but maybe we can try it out? Would links to a xml view link to the entire file or would it be possible to display just the relevant section?

[PietroLiuzzo]

we could link to the relevant section

[PietroLiuzzo]

for point 4 the list should IMHO include

1. elements which have a specification in the schema
   • antiphon
   • listRelation
   • msDesc
   • del
   • binding
   • add
   • creation
   • date
   • personGrp
   • origDate
   • citedRange
   • condition
   • term
   • language
   • ref
   • title
   • listBibl
   • occupation
   • faith
   • nationality
   • roleName
   • bibl
   • ptr
   • witness
   • dimensions
   • desc
   • dim
   • ab
   • seg
   • decoNote
   • custEvent
   • msPart
   • msItem
   • colophon
   • handNote
   • editor
   • change
   • height
   • persName
   • placeName
   • place
   • material
   • explicit
   • incipit
   • objectDesc
   • note
   • relation
   • div
   • TEI
   • origin
   • geo
   • date
   • locus
   • item
   • supplied
   • space
   • gap

this is the list as it appears in the schema file, we could tidy up and further document that as well. In many cases the rules in the schema are only for the control of the id or for a list of values of a specific attribute.

2. elements not further specified in our schema which we might use in a specific way in specific context (not including again those in the previous list)

   • idno
   • repository
   • collection
   • country
   • settlement
   • region
   • rubric
   • notatedMusic
   • textLang
   • q
   • measure
   • cit
   • quote
   • summary
   • rubric
   • lb
   • l
   • pb
   • cb
   • watermark
   • signatures
   • depth
   • width
   • layoutDesc
   • layout
   • surrogates
   • person
   • category
   • catDesc
   • graphic
   • handShift
   • subst
   • choice
   • witness

3. elements in the TEI header of frequent use but not further specified in our schema like (not including again those in the previous lists)

   • p
   • hi
   • foreign
   • abbr
   • ex
   • expan
   • seal
   • language
   • unclear
   • orig
   • rdg
   • lem

4. other "container" elements (not including again those in the previous lists)

   • msIdentifier
   • msContents
   • physDesc
   • history
   • additional
   • supportDesc
   • handDesc
   • decoDesc
   • additions
   • collation
   • foliation
   • filiation
   • msFrag
   • list
   • bindingDesc
   • sealDesc
   • origin
   • origPlace
   • provenance
   • acquisition
   • source
   • listPerson
   • keywords
   • taxonomy
   • facsimile
   • listWit
   • listApp
   • app

[PietroLiuzzo]

most of these alone would not help anyhow, but it makes sense that there is a page onthe guidelines for each of the first group should show

• definition from TEI and link
• directions of use (prose)
• rules and alteration from the schema
• examples
• link to ontology if the element produces annotations in RDF
• links to pages and indexes of the guidelines where the element is used

the second group would need

• definition from TEI and link
• directions of use (prose)
• examples
• link to ontology if the element produces annotations in RDF
• links to pages and indexes of the guidelines where the element is used

the third group might need only

• definition from TEI and link
• examples
• links to pages and indexes of the guidelines where the element is used

the last group instead would only need

• definition from TEI and link
• links to pages and indexes of the guidelines where the element is used because the examples will be very likely already in pages which face a specific part of the encoding and use it in context.

I would leave the may contain and is contained information for each element to the TEI guidelines and avoid reproducing it.

[PietroLiuzzo]

from point 1 and 2 of the initial post I think there is already a first organizational principle

from the home page the user will be able to search (simple text search, no advanced functions) and will have the following links

1. workflow guidelines
2. bibliography guidelines
3. encoding guidelines
   • general
   • manuscripts
   • works
   • places
   • persons
   • narratives
   • institutions
   • authority files
   • corpora
   • Art Themes
4. list all elements
5. schema (will display directly the schema and the rules encoded there)
6. ontology browser
7. how tos (oxygen/atom hints)

each of these will be a page and I imagine the third group will have the features of point 3 in the original post

• descriptions of the records following their structure
• links to TEI for the used elements
• links to the pages of the used elements and attributes

however these risk to become again very big, and I would suggest to

• have subpages with specific themes
  • transcription
  • physical description
  • binding description
  • editions
  • relations
  • ref, corresp, target
  • xml:id
• link each reference to an element or attribute name to the relevant page
• point 7 of the original post for each page and subpage

[PietroLiuzzo]

we will use these elements for the encoding of the guidelines (more TEI! :) ) http://www.tei-c.org/release/doc/tei-p5-doc/de/html/TD.html#TDphrase

[PietroLiuzzo]

further issues about the guidelines to be opened here https://github.com/BetaMasaheft/guidelines/issues