Closed HazardJ closed 9 years ago
troy
commented
9 years ago Could you provide some back story here? The changes totally change the format -- it's now something other than basic markdown. I'd welcome as much explanation as you'd wish someone would give you when submitting a PR like this :)
HazardJ
commented
9 years ago Hi Troy,
You’re right. Needs a back story. Maybe a pull request is not the right communication. What I wanted to say is that we’re creating a repository of automated legal docs on GitHub. I forked some from Jason Boehmig, a buddy, and spotted yours. So I made the changes and did a demo at http://commonaccord.org/index.php?action=source&file=./Papertrail/Employment.md.
Maybe an email would have been more appropriate than a pull request.
Cheers, Jim
On Dec 8, 2014, at 6:54 PM, Troy Davis notifications@github.com wrote:
Could you provide some back story here? The changes totally change the format -- it's now something other than basic markdown. I'd welcome as much explanation as you'd wish someone would give you when submitting a PR like this :)
— Reply to this email directly or view it on GitHub.
Jim Hazard @hazardj 650.454.5007
troy
commented
9 years ago Thanks, @HazardJ. What did you hope would become of the PR? It changes the .md files so they're no longer Markdown (or don't seem to be), even though they still have the same extension.
As feedback, a couple things I wondered while browsing your site:
troy
commented
9 years ago BTW, no need to answer these here, they're immaterial to the PR. Just stuff for your site.
HazardJ
commented
9 years ago Hi Troy,
Dazza Greenwood of the MIT Media Lab suggested .md would make the files a lot easier to read on the GitHub site. He was right. So, even if not conforming (and until our tiny community gets big enough to decide otherwise) it seems a good hack.
Documentation is scattered. I just made a page pulling together some of what we have. I’ve been at this for years, so there is a lot, but it is scattered and idiosyncratic.
https://github.com/CommonAccord/Org/wiki/How:-Data-Model
Docracy was a noble adventure. I talked with Veronica early on. Also pulled some docs from their site (which seems now to be down). But the thing to version is the source code of documents, not the rendered docs. No one really had a source format for legal docs.
Jason Boehmig (Series Seed, etc) is a buddy.
Yes, NFP. Law is a public good. Private models of legal docs, while they abound, depend on the friction of word processing.
Jim
On Dec 9, 2014, at 11:58 AM, Troy Davis notifications@github.com wrote:
Thanks, @HazardJ. What did you hope would become of the PR? It changes the .md files so they're no longer Markdown (or don't seem to be), even though they still have the same extension.
As feedback, a couple things I wondered while browsing your site:
is "A modular template system of cards that is the simplest possible programming language" used and documented anywhere (and ideally, standardized, but at least http://daringfireball.net/projects/markdown/)? That's basically table stakes, probably before expecting anyone else to use it. can this be done with an existing format? This and this make me wonder whether a new format - rather than adapting Markdown or something else - would ever win. is CA a not-for-profit? If not, what is it? — Reply to this email directly or view it on GitHub.
Jim Hazard @hazardj 650.454.5007
troy
commented
9 years ago It makes the markdown a notch above unreadable and unparsable by anything else, so I guess I disagree with that conclusion (regrettably -- I wish it was a clean hack). Have any other ideas? The format isn't in use anywhere, so it wouldn't justify a second file.
HazardJ
commented
9 years ago Fair enough. Thanks for the chat. Do please consider the counter-weighing benefits - automation of law. If you find a way of squaring the circle, we’d gladly accept a PR.
On Dec 9, 2014, at 1:36 PM, Troy Davis notifications@github.com wrote:
It makes the markdown a notch above unreadable and unparsable by anything else, so I guess I disagree with that conclusion (regrettably -- I wish it was a clean hack). Have any other ideas? The format isn't in use anywhere, so it wouldn't justify a second file.
— Reply to this email directly or view it on GitHub.
Jim Hazard @hazardj 650.454.5007
troy
commented
9 years ago I guess I'd encourage thinking of this as a challenge for you and the project, rather than a problem with either this repo or PR. That is, you've got a chicken-or-egg problem right now: a single tool that only supports a currently-unused file format. I don't think making markdown files incompatible and hard to read is the solution, but maybe starting with either the tool or the format - not both - makes more sense.
As an example, if you're focused on changing the legal industry, how about ingesting standard text files and allowing document-specific template string(s), like for entity names? Sure, they're not perfect, but it's 90% of the result with 10% of the effort and no breaking changes.
HazardJ
commented
9 years ago Hi Troy,
Thanks for the good thoughts.
We more or less take your last thought and generalize it. Of course, some strings are variables, but once you get started, you find that there is no stopping place. Nearly everything in a document might change and if you look across a bunch of uses, everything does change. So we start with the notion that the “document” is the value of the variable “Model.Root” with each {variable} in the string expanded. The string could be a whole legal form with only a few variables for deal points (effectively a blob), but key/values let it be treated as an object.
The example at: http://commonaccord.org/index.php?action=source&file=./Papertrail/Demo_Acme_Shirley.md shows your doc treated mostly as a blob, but with an override of the cumulative remedies clause (7.sec), marked.
From this perspective, the .md extension is pure opportunism. The key/value format isn’t markdown and the values use html. The key/values could be expressed in json or anything else that supports a key/value notion. Given where we are, .md makes the file look better on GitHub, which is something of a help for browsing or editing there.
Again, good thoughts, and it makes me more cognizant of both the meaning of a pull request and of .md.
Jim
On Dec 9, 2014, at 1:43 PM, Troy Davis notifications@github.com wrote:
I guess I'd encourage thinking of this as a challenge for you and the project, rather than a problem with either this repo or PR. That is, you've got a chicken-or-egg problem right now: a single tool that only supports a currently-unused file format. I don't think making markdown files incompatible and hard to read is the solution, but maybe starting with either the tool or the format - not both - makes more sense.
As an example, if you're focused on changing the legal industry, how about ingesting standard text files and allowing document-specific template string(s), like for entity names? Sure, they're not perfect, but it's 90% of the result with 10% of the effort and no breaking changes.
— Reply to this email directly or view it on GitHub.
Jim Hazard @hazardj 650.454.5007
troy
commented
9 years ago Cool, and you too with the good conversation. LMK if I can bounce around ideas or be useful - I and Papertrail definitely value the goal.
We're doing legal docs on github. Looked around for some others doing the same. Pulled and did the little changes to put your doc in our format for automation.