Re: [legalcitem] GitHub etc.(long post...sorry)

[Frank Bennett <biercenator@gmail.com>]

On Thu, Nov 20, 2014 at 6:40 AM, John Quentin Heywood
<heywood@wcl.american.edu> wrote:
> Hi Folks,
>
> Couple of things:
>
> 1. The GitHub repository was discussed in the main TC meeting this morning,
> as was other off-site tools such as GoogleDocs. Ken pointed us to the OASIS
> Technical Committee (TC) Process document at
>
> https://www.oasis-open.org/policies-guidelines/tc-process
>
> particularly Section 2.8 on TC Visability, which says:
>
> The official copies of all resources of the TC and its associated
> Subcommittees, including web pages, documents, email lists and any other
> records of discussions, must be located only on facilities designated by
> OASIS. TCs and SCs may not conduct official business or technical
> discussions, store documents, or host web pages on servers or systems not
> designated by OASIS. All web pages, documents, ballot results and email
> archives of all TCs and SCs shall be publicly visible.
>
> Both GitHub and GoogleDocs would seem to be in conflict with this, although
> as it was pointed out in the call, at least GitHub is an open standard,
> which can't be said about GoogleDocs. Many folks on the call were less than
> happy with the OASIS Wiki, which would seem to be the only official
> collaboration tool available. It was suggested that getting the work done
> was important, so perhaps we could use private tools such as GitHub as long
> as we put the official documents on the SC's public document repository,
> which would be here:
>
> https://www.oasis-open.org/committees/documents.php?wg_abbrev=legalcitem-courts
>
> and conduct our technical discussions on this listserv. This seems
> reasonable to me.
>
> Now Frank has been doing some wonderful work on GitHub, merging the reporter
> data from CourtListener and the CSL project with what we have been doing and
> making it truly usable for us and other projects (like the Free Law
> Project). He thinks we should open the repository up so that others can
> collaborate. I agree, and I think this would dovetail nicely with the OASIS
> rules. If the work being done on the GitHub repository is no longer
> officially OASIS work, we don't have to worry about their rules. The GitHub
> repository becomes a tool for the whole free law community, that we in the
> OASIS SC can use as a resource for our work. We could rename it to something
> like the "Court Citation Project" or even something less lame than that. How
> do folks feel about this?
>
> For some examples of what Frank has done, look at:
>
> http://jqheywood.github.io/CourtsSC/index.html
>
> and
>
> http://jqheywood.github.io/CourtsSC/states.html
>


Terrific!

One question: Should I then remove the reference to OASIS from the
header of the online docs?

    http://jqheywood.github.io/CourtsSC/index.html

That seems stingy, by it would indeed reduce the potential for people
to take the work-in-progress as some sort of draft standard.

If I read correctly, then, the repo itself can be made public? That
would be great - there are already people out there ready to
contribute to the effort.

Some notes about infrastructure changes in the works chez CourtsSC ...

For the CourtsSC docs, the next step will be to generate them directly
from a filesystem data hierarchy of the content (which exists as of
yesterday), with links on each court and reporter to their discrete
source files in the GitHub filesystem. I think GitHub now
automatically performs a fork and pull request when people without
write permissions to an edit, so that will give us easy-access editing
by outside contributors, and an editorial workflow for maintaining
control over the end product.

For extension and reorganization of the source files through the
GitHub online UI, I'll add an explanation of how that works to a
README displayed on every source page. So that will be covered as
well.

Finally, we'll need to work on validation and output. For that, we
should have a discussion about what the constraints should be (beyond
producing parseable source and valid XML). Then I can start mucking
around with code.

With validation in place, we'll be ready to tie the whole thing into TravisCI.

    https://travis-ci.org/

Once on-the-fly validation is working, we'll be ready for scalable
crowd-sourcing.

I guess a final item will be the output. The current rendered view is
handy for examining and working with the source structures, but
machines will want something else. We should be able to generate it
automatically, once we know what it is.

Frank

>
> 2. In response to the discussion in our last SC meeting, and never being
> afraid to play the fool (or, if you ask my kids, BE the fool, but I
> digress), I asked the assembled TC what exactly a use case was, and what are
> we supposed to be producing. Everybody seemed happy that I had asked.
> Someone (I'm not sure who) described it thusly: HTML5 is the standard, a web
> page demonstrating all the different parts of HTML5 is the use case. John J.
> reminded us all that the SCs should not get lost in the weeds of detail, as
> he has seen other projects flounder because of it. We should be looking for
> the common things in these citations and writing them up. I think we may be
> close to ready for this in the US context very soon.
>
> Well, time to go home and make my eldest his birthday dinner (he turned 17
> today),
>
> John
>
> --
> John Quentin Heywood
> heywood@american.edu