The case for Authoring

[Jason Harrop <jharrop@speedlegal.com>]

John McClure wrote (in part - see below for full text):
 > A key issue dividing the subcommittee is what is the key use case for which
 > we're designing a set of elements? For me, it is very simple: one party sends
 > an XML file over email to another party. That party prints the document twice,
 > signs it, and returns both copies to the sender by post. The originating party
 > signs both copies, and sends one copy back to the second party.
 >
 > This is unquestionably true document EXCHANGE. If we can't accomplish this
 > level of functionality, I do think we've failed to create a standard for the
 > exchange of legal documents in today's world.
:
 > The key use case for J&P seems to be the ENTRY of the document into some
 > software program -- hence their constant focus on the "user experience" when
 > that program happens to be a schema-driven software application.

Unquestionably our standard needs to be compelling for some group of users if it 
is to be a success.

John identifies the scenario of sending an XML file over email, which is then 
printed out, as "key".

But i wonder what group of users would find this compelling? What's wrong with 
sending PDF or RTF/DOC, and printing it out?  Where are all the people 
complaining this doesn't work? (I don't believe this has been a pain for anyone 
since the transition from Word 6/95 to Word 97, and it won't be a pain again 
unless/until StarOffice/OpenOffice starts to be adopted in our target user 
communities)

And can we deliver on it today (assuming we send eContracts XML), given that 
iirc John says elsewhere that XSL is necessary for headers/footers?  At the very 
least, the XSLT would need to be published somewhere, which probably isn't 
consistent with 8.1.1-8.1.3 of XML Signature Syntax and Processing.

Having said that, our standard should facilitate this sort of exchange (and 
there is nothing in what Peter and I have proposed which prevents it).

Its just that in and of itself, sending an XML file over email, and printing it 
out is pretty unexciting, and hard to see as key.

In fact it seems to me that where the email exchange example starts to become 
interesting is where you need XML rather than PDF or RTF, in order to do 
something best done with the XML.

This may mean negotiation (where authoring is required), or once the terms are 
agreed, downstream use (eg in a contract management system).


John McClure wrote:
 > Let's stop
 > kidding ourselves -- most working attorneys don't want to screw around with
 > markup.... certainly not while they're composing contract language. They
 > want a sofware application that handles the markup for them, that has a
 > clause library, and so on.
 >
 > So, I believe that the key use case concerns document assembly and printing.
 > not the entry of XML markup to an XML markup editor.

Document assembly software applications are of course becoming increasingly 
common - some vendors (such as SpeedLegal) use XML for this, and others (most) 
don't.

But - and this is a critical point - someone has to author the template 
contracts and the clauses which appear in the clause library you refer to.

In my experience, these people are attorneys or other people who do not have an 
IT background, and know nothing about HTML or XHTML (unless they have web 
publishing as a hobby).

Assuming an eContracts XML environment, those people will probably use XML tools 
to create the contracts and clauses.  (If instead they use Word or WordML, and 
this is converted to eContracts XML, an understanding of our document structure 
will still help them to understand what they are doing)

So why make the markup difficult for these authors?

We envision that a subset of lawyers (ie those lawyers that create the 
templates) would initially use eContracts XML.

All the other lawyers of course are engaged in drafting contracts tailored to 
the needs of particular clients and their transactions.  For the most part, 
today this is done using Word.

But other tools could be adopted, if they offered sufficient advantage.  Why 
foreclose or reduce the chances of this happening by creating a standard which 
is hard to understand? Such a standard contains unnecessary barriers to 
adoption.  It doesn't matter how elegant it is technically, if the users can't 
use it, it will go nowhere. Remember simple ugly HTML 1.0, and how well it took off?

To attempt to place authoring out of scope seems to me to be misguided. 
Excluding it in order to get rid of the constraints it places on our markup 
seems like a cop out.

To exclude it would also be inconsistent with our charter and the road we as a 
TC have walked so far.

 From our charter, our Mission includes "the efficient creation, .. of contract 
documents and contract terms".

 From our charter, our scope includes the creation of DTDs that "can be used by 
parties: 1. negotiating and finalizing contracts in an application neutral format."

It also involves meeting the requirements of end users.  The authoring 
requirement plays a role in five of the scenarios submitted to the TC:

- law firm contract creation and negotiation
- enterprise contract management
- Contract Generation Systems
- XML in Enterprise Documentation Systems
- Construction Contract Preparation and Management

That authoring is involved is an underlying assumption which permeates the TC's 
Clause Model Requirements document, and is included in the specific requirements.

John, if you seriously think authoring should be out of scope, then please 
suggest a motion for consideration at the next teleconference.

cheers,

Jason




John McClure wrote:
> (g) Key use cases and assumptions
> 
> 	A key issue dividing the subcommittee is what is the key use case for which
> 	we're designing a set of elements? For me, it is very simple: one party sends
> 	an XML file over email to another party. That party prints the document twice,
> 	signs it, and returns both copies to the sender by post. The originating party
> 	signs both copies, and sends one copy back to the second party.
> 
> 	This is unquestionably true document EXCHANGE. If we can't accomplish this
> 	level of functionality, I do think we've failed to create a standard for the
> 	exchange of legal documents in today's world. Certainly in the future, the
> 	digitally signed stream will be returned by email not by post, but there will
> 	always be the desire to print out and file that paper document -- to ignore
> 	that reality would be gravely stupid.
> 
> 	The key use case for J&P seems to be the ENTRY of the document into some
> 	software program -- hence their constant focus on the "user experience" when
> 	that program happens to be a schema-driven software application. But I've got
> 	to ask: what percentage of stakeholders truly plan to enter a contract using a
> 	raw markup editor? I have no numbers, but the idea of it to an economist such
> 	as myself is patently absurd -- that tool would not maximize the efficiency of
> 	the parties to the contract. Rather those persons would be more productive
> 	using a tool that assembled the contract for them to the extent possible (from
> 	templates and clause libraries for instance), and which then enabled them to
> 	add, modify, or strike content from the assembled base document.
> 
> 	In my opinion, there is no contest here -- we achieve maximum success by a
> 	standard that caters to the greatest majority of anticipated use. Let's stop
> 	kidding ourselves -- most working attorneys don't want to screw around with
> 	markup.... certainly not while they're composing contract language. They
> 	want a sofware application that handles the markup for them, that has a
> 	clause library, and so on.
> 
> 	So, I believe that the key use case concerns document assembly and printing.
> 	not the entry of XML markup to an XML markup editor. So it is SOFTWARE
> 	AUTHORS who need to understand our standard in depth, for they are writing
> 	the code that produces the markup mandated by our standard. Over time,
> 	when one considers the many elements needed for semantics, then markup
> 	editors become even less practical.
> 
> 	How does the key use case relate to our standards development? First, it
> 	provides a wide opening for unverifiable assertions about the "ease	of use"
> 	of one markup alternative over another. Second, it ultimately determines 
> 	what elements are included in the standard -- under my key use, enabling
> 	the contract to be printed, then the key elements are ones to transmit
> 	layout constructs, such as headers footers and positioned content. If
> 	the focus is merely on entering the contract to a raw markup editor, then
> 	there is not much need for such "after-the-fact" composition, since it is
> 	envisioned to be outside the scope of our standard, more in the province of
> 	document assembly software that "adds headers and footers and cover
> 	pages and tables of contents" I was told once the attorney has crafted the
> 	language. But, it's pretty clear that WYSIWYG displays (what you see...) form
> 	the baseline for word processors -- today used by 100% of law firms. It just
> 	seems to me that a standard that is unduly focused on the needs of a small
> 	number of non-WYSWYG attorneys is going to cause problems for its long
> 	term success.
> 
> 	My point is this. I come from a technician's perspective -- 30 years worth,
> 	from the days of UNIVAC and 029 card punch machines. As an architect. I
> 	demand technical justifications support technical designs, such as an XML
> 	markup dialect is. Key use cases centered on the "user experience" while
> 	performing, essentially, text entry for a contract , ultimately has meant that
> 	technical merits of one approach are prone to being jaw-droppingly trumped
> 	by claims about someone who isn't really a particularly typical user at all.
> 
> 	The ease of use during text entry using a schema-driven editor is totally
> 	dependent on the way that application was programmed. In the <area>
> 	discussion, the argument is about element names vs element attributes.
> 	Utlimately, there's going to be 2 lists that such a user would have -- one
> 	of names, and one of attributes -- that's not going away, and is pretty
> 	central to the very definition of a schema-driven editor, i.e., software
> 	that exposes a schema directly to an end-user.
> 
>