What is the naming scheme?!

[HazardJ]

@HazardJ has been fiddling with naming schemes for some years. With this repository, it is proposed that we take advantage of found objects - to wit, the WorldWideWeb and GitHub. So, files can be organized according to the web domain of the proponent, or according to the Github organization and repo name. These can be managed as local files, or the whole of GH/ and W/ (or GitHub/ and WWW/ ?) can be aliases for files at those destinations.

See https://github.com/CommonAccord/Cmacc-Startup2/blob/master/Doc/include.php (@dazzaji, someone else, how do I make a link to a file in the repo?)

This defines, in essence, a proponent's exclusive space.

Within that space it is suggested (by me and my experience) that we suggest a type of organization. This is of course not mandatory, but might be helpful. My experience is that two folders are helpful - one for forms and the other for components. Most components of most forms will be "sections" so, Form/ and Sec/. Note the initial caps. This distinguishes from the web domains, and CamelCase is easier to read (@dazzaji has made this point, too).

From there, we get into mostly details, but one of them stands out. The "extension" of the files (.md, but could have been .cmacc or the like), is important. It tells GitHub how to present the file when you go to the source there. It tells your computer what editor to use when you double-click the file. We have been using .md and had good experience with that. It has been objected that we are overloading the .md extension name. That a Cmacc file is not markdown. It's something else. That seems accurate as a technical matter, but pragmatically, .md works well. So if/until GitHub makes special accommodation for .cmacc or the like, I suggest we stick with .md. (Note that some common files don't have .md, such as the ones that make outlines, in Z/. It seems pedantic to have those rarely edited bits have .md, and adds a bit of cruft when you use them.

The next most systemic issue is probably the names that denote parts of a document. In the Z/ folder, there are lots of little widgets that make it easy to put documents together or cut up an existing document and automate it. These are of course not exclusive, they are just more folders of files, and we can always make more. They assume an organization of sections as "Sec" means a section and its title. "sec" means the content of the section (without its title). "Ti" (chosen because it works in English/French/German and probably a lot of places of romance) means Title/Titre/Titel. Within the content of a section (the "sec" part) there is the possibility of an introductory line or paragraph, then a list, and then an extroductory line or paragraph. There is a naming convention for those, too, built into the stuff at Z/. The intro is 0.sec, the extro is 90.sec (if you have more than 89 paragraphs in a section you either rethink it or make your own). They could be Intro.sec and Extro.sec just as easily (remember that everything is just names, there is no calculation).

Into the weeds:

The name of the actual files (as opposed to the folders that organize them) could be long and expressive. I've played with that a lot. But, that seems cumbersome and a bad tradeoff. More sensible is to make the file names short and merely state their function. So ... Wx/org/nvca/SPA/Sec/cRep_v01.md is the Company representations. This could be made more expressive - /CompanyRepresentations_v01.md, though if you work with these files a bit, cRep is a bit less work to read. But, skipping that weed on a weed, the point is that I didn't name the file NVCA_SPA_cRep_v01.md. Because that info is already in the path. This works fine as long as the file is in the file system. Which is where it should be, so this seems a better than the repetition of Wx/org/nvca/SPA/Sec/NVCA_SPA_cRep_v01.md.

Out onto the fields:

Of course all of these things can be further automated. The Z/ things could be done as some bit of code that provided quicker responses, had more features and didn't take some 800 files to count to 40. The W/ could actually fetch from the web, and GH/ from GitHub.

The form of a variable - {some thing} - allows spaces, so one can put programming expressions into a document and your parser could default (after looking to see if there was a literal keyname match) to a programming environment. This has lots of potential uses, and is totally necessary for even such common tasks as adding price times quantity. Automatic numbering of cross-references is another common example. There is a pretty good way to do it natively, but perhaps people will want this to be fully automated.

Above our heads:

All this CommonAccord text is legal fodder for real deals. It can be used natively (Be-Bound does.) But it is most likely to be a resource for real transaction systems - such as blockchain. So, the fit with identity and place (U/) and with automation (adding price times quantity and applying a discount) will be done in those systems. CommonAccord, and the Cmacc document model, is a place to do text.

[HazardJ]

@zmon suggested that the super-short top-level names were too short. D/ for deals or documents, P/ for private, W/ for world wide web, etc. I fully understand that they at first mean nothing, and might be a factor in throwing (or putting) people off when they first encounter them. The advantage of these super-short ones is that they don't take up much time for the eye when reading a page like http://new.commonaccord.org/index.php?action=source&file=/Wx/com/cooleygo/US/NDA/Form/Doc_v01.md . And I suppose a parallel is with top-level domain names, which are short. So, my feeling is to leave them as is, but I am eager for other views. Everything is mutable, but picking a good path could save a bunch of broken links in future.

[HazardJ]

An issue came up yesterday (I managed to duck it) of where CommonAccord "core" materials might go. Materials that are not associated with any particular contributor (and therefore at either GH/ or W/). Of course, one could say that they are CommonAccord materials and therefore should be in GH/commonaccord/SomeRepoName/Doc/ ... or W/org/commonaccord/SomeFolderName/Doc/. That seems a plausible solution. Or should there be a core space - such as S/ for shared?

[mdangear]

If I think in terms of Open Source, then I would agree that a S/ for Shared folder would make sense. This is where the official "release" can be. In Open Source you start from a Debian release and then you can build your own system by modifying it. The same should happen over time with Cmacc. As a new user I could install the package, the S/ is what can be used across and all the other stuff are the more exotic documents that others are working on.
The virtue of such a S/ directory is that we can also set up an approval process, so that what is shared through W/ or GH/ is moved into S/ to become a part of the official core.

[HazardJ]

Sounds right to me.
On Oct 2, 2015 09:14, "Marc Dangeard" [email protected] wrote:

If I think in terms of Open Source, then I would agree that a S/ for
Shared folder would make sense. This is where the official "release" can
be. In Open Source you start from a Debian release and then you can build
your own system by modifying it. The same should happen over time with
Cmacc. As a new user I could install the package, the S/ is what can be
used across and all the other stuff are the more exotic documents that
others are working on.
The virtue of such a S/ directory is that we can also set up an approval
process, so that what is shared through W/ or GH/ is moved into S/ to
become a part of the official core.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

[mdangear]

So now we have a new project to create the first release of the S/ directory. Maybe a package for startups that would include NDA, Agreements to hire consultants and employees, Stock purchase agreement 👍

[HazardJ]

Makes sense to put original stuff that has achieved a level of consensus in
S/. To the extent possible, I would like materials to remain in the
domains of their original advocates and maintainers. So ... NVCA docs
would remain in W/org/nvca (if they pick it up) and Wx/org/nvca until they
do. We can patch them in S/ or if we find that somehow a really codified
approach has arisen, it can go there. So ... S/001/ would mostly be a
bunch of links to things like W/org/nvca ... It could have Z/ stuff
there, too.

Make sense? We are feeling our way, but it feels like real forward motion.

On Fri, Oct 2, 2015 at 9:23 AM, Marc Dangeard [email protected]
wrote:

So now we have a new project to create the first release of the S/
directory. Maybe a package for startups that would include NDA, Agreements
to hire consultants and employees, Stock purchase agreement [image: 👍]

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

@CommonAccord

[mdangear]

The key once we get to that point is to have "one source of truth", so I am not sure about having docs in 2 places, and I am not sure about having docs in S/ be just links to docs in other places. What if the doc behind the link gets changed? The idea of moving content to S/ is to stabilize code/docs. So if it is in S/ it is the stable approved version that can be shared by individuals or companies in deals, and it does not prevent the original doc to keep evolving if this is what the author wants.
Rather than just a link, I would place a doc in S/ with a link back to the original author so that he/she gets the credit and so that people can go see how the doc is evolving beyond the official approved version.

[HazardJ]

I think that problem does not arise. The repo will consist of a number of
top level folders, including GHx/, S/, Wx/ (and depending on how it is
done, GH/ and W/). So your copy of the repo will have all that stuff that
is referenced, too. It is just a naming thing. Keeping the names closely
associated by author/origin makes sense. If you brought the nvca stuff
into S/01/ you would call it S/01/W/org/nvca which seems more complex than
W/org/nvca.

On Fri, Oct 2, 2015 at 11:21 AM, Marc Dangeard [email protected]
wrote:

The key once we get to that point is to have "one source of truth", so I
am not sure about having docs in 2 places, and I am not sure about having
docs in S/ be just links to docs in other places. What if the doc behind
the link gets changed? The idea of moving content to S/ is to stabilize
code/docs. So if it is in S/ it is the stable approved version that can be
shared by individuals or companies in deals, and it does not prevent the
original doc to keep evolving if this is what the author wants.
Rather than just a link, I would place a doc in S/ with a link back to the
original author so that he/she gets the credit and so that people can go
see how the doc is evolving beyond the official approved version.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

@CommonAccord

[HazardJ]

Another way of putting this is:

I think you do not want to have 1) a single supplier or 2) the bottleneck
of committee thinking, when you could have a variety of sources each with
their own strengths competing and conversing.
On Oct 2, 2015 11:47, "James Hazard" [email protected] wrote:

I think that problem does not arise. The repo will consist of a number of
top level folders, including GHx/, S/, Wx/ (and depending on how it is
done, GH/ and W/). So your copy of the repo will have all that stuff that
is referenced, too. It is just a naming thing. Keeping the names closely
associated by author/origin makes sense. If you brought the nvca stuff
into S/01/ you would call it S/01/W/org/nvca which seems more complex than
W/org/nvca.

On Fri, Oct 2, 2015 at 11:21 AM, Marc Dangeard [email protected]
wrote:

The key once we get to that point is to have "one source of truth", so I
am not sure about having docs in 2 places, and I am not sure about having
docs in S/ be just links to docs in other places. What if the doc behind
the link gets changed? The idea of moving content to S/ is to stabilize
code/docs. So if it is in S/ it is the stable approved version that can be
shared by individuals or companies in deals, and it does not prevent the
original doc to keep evolving if this is what the author wants.
Rather than just a link, I would place a doc in S/ with a link back to
the original author so that he/she gets the credit and so that people can
go see how the doc is evolving beyond the official approved version.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

@CommonAccord

[mdangear]

The process I suggest does not imply any bottleneck. We do not care how long it takes to get docs into a S/, what it is instead is a process of solidification of the base that is still valuable. And anybody can use the whole anyway as you mention, so until a doc is solified into S/ it is still available.
The value is that once it has become a standard and it is moved into S/ then negotiations are easier.
Parties can agree to use docs from S/ version 20150920 plus whatever else needs to be used. All docs from S/ 20150930 are a given and we do not need to worry about them, and then we can customize on top of that base for a specific deal.

[HazardJ]

But you can do the same with W/org/nvca/v01/.... , right?

On Fri, Oct 2, 2015 at 2:36 PM, Marc Dangeard [email protected]
wrote:

The process I suggest does not imply any bottleneck. We do not care how
long it takes to get docs into a S/, what it is instead is a process of
solidification of the base that is still valuable. And anybody can use the
whole anyway as you mention, so until a doc is solified into S/ it is still
available.
The value is that once it has become a standard and it is moved into S/
then negotiations are easier.
Parties can agree to use docs from S/ version 20150920 plus whatever else
needs to be used. All docs from S/ 20150930 are a given and we do not need
to worry about them, and then we can customize on top of that base for a
specific deal.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

@CommonAccord

[mdangear]

Yes except more complicated, because either I am stuck into one system, for example NVCA, W/org/nvca/v01/ or I have to define that I want the NDA from NVCA and the MOU from W/com/BeBound/V02 and the consulting agreement from W/com/KPMG/v01 etc...
The value of the S/ would be to provide one place with the best of the W/ stuff, all in one place and all working together. Plus I know that the S/ stuff took from the W/ directory and had gone through the review process in order to a approved as a standard that could be added to S/
As a business it makes my life easier.

[HazardJ]

We can of course put a copy of W/org/nvca/v01 into S/ 20151002 (or S/v01/),
but a link is just as good so long as the referent doesn't change. (There
is the same mechanism - git - for assuring that changes haven't happened in
either place.) And the idea of freezing a large group of different
documents with different community dynamics seems cumbersome to me.

The idea of curating a list and managing it is very attractive. The Demo
D/Acme/ is a start on that, and on helping to assure that all the docs we
point at are consistent in such things as names for persons, places, etc.
As a first step, what would you like to see added to the Demo at D/Acme ?

On Fri, Oct 2, 2015 at 2:50 PM, James Hazard [email protected]
wrote:

But you can do the same with W/org/nvca/v01/.... , right?

On Fri, Oct 2, 2015 at 2:36 PM, Marc Dangeard [email protected]
wrote:

The process I suggest does not imply any bottleneck. We do not care how
long it takes to get docs into a S/, what it is instead is a process of
solidification of the base that is still valuable. And anybody can use the
whole anyway as you mention, so until a doc is solified into S/ it is still
available.
The value is that once it has become a standard and it is moved into S/
then negotiations are easier.
Parties can agree to use docs from S/ version 20150920 plus whatever else
needs to be used. All docs from S/ 20150930 are a given and we do not need
to worry about them, and then we can customize on top of that base for a
specific deal.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

@CommonAccord

@CommonAccord

[mdangear]

Curation is a key word 👍

[HazardJ]

Yup. We can square this circle. With no problem.

On Fri, Oct 2, 2015 at 3:02 PM, Marc Dangeard [email protected]
wrote:

Curation is a key word [image: 👍]

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

@CommonAccord

[HazardJ]

So ... here's one square - http://new.commonaccord.org/index.php?action=list&file=/Dx/Acme/ - which posits a small company that has made a bunch of agreements. By selecting these agreements, we can suggest what we think are forms we think a company like Acme should use. That curates, in a particular context. Context is important. Of course (@dazzaji) each such use is an up-vote on the form, roughly visible via "Used By" on the form's page and fully analyzable if you treat this stuff as a graph.

What should we add - a consulting agreement? Then employment? Or a license or distribution agreement?

[dazzaji]

With regard to naming - what I'd suggested in the past and continue to recommend is:

Identify what needs naming

Identify two types of items: a) what you believe requires naming and b) what you believe requires some fixed or relative position (such a position in a subdirectory or a root directory)

Don't Definitively Name Yet, Just Identify

This time, try resisting the urge to just name it again and again and instead use a unique identifier as a placeholder only. That means each item above would get a number or letter or alphanumeric if there are clear clusters (eg A, B, C1, C2, D, E).

Create a decision table

Create a table with

• the item identifiers on the left column,
• a one sentence description in the next column,
• past examples of how you have named it in the next column, and
• candidate names in the next column.

People like me and other contributors to and supporters of CMAC can help garner good feedback using the decision table

Update the table with feedback from time to time

I invite you to use the FutureCommerce Hackathon in Nov 21/22 as major opportunity to garner feedback and establish advances toward rational, documented and validated naming conventions that can result in a really solid release of Version 2. consensus.

Use a Target Date before 2016 for release version 2. of CMAC

Naming Consensus should be part of a facelift for CMAC with to sharpen the practices it can be called "Version 2" and can/should have a target release date.

[HazardJ]

Good stuff.

Yes, canonical naming schemes are profoundly restrictive. I think we achieve what you suggest - arbitrary names that can be mapped by meaningful names.

In CommonAccord we can do unlimited mapping and remapping at the graph level, but the file-naming was a persistent problem. The 90% solution seems to be to base file names on web domains and GitHub repo names (and any other system of naming that has traction).

Within a document

The part that seems easiest and most stable is within a document. Most legalish documents can be understood as an outline with some stuff before and after, and the numbers of the sections offer a ready naming scheme. This doesn't work for all documents, but for most of them. That led me to make a kit of section frameworks: Z/ol/, Z/paras/ etc. A tool, not a rule, but it saves a lot of work and it harmonizes.

The "graph" of prefixing

The next step can be to take the sections and make them into separate pages, and reference the pages using "meaningful" prefixes. You end up with a "meaningful" list of the sections, etc. Of course, someone else can use the section pages using different prefixes, so we retain flexibility - escape the trap of having to agree. As a "graph", there can be an unlimited number of uses of a section, via whatever prefixes anyone wants.

The same thing can be done at the document level. I can have a list of preferred documents, each with a prefix -

SharePurchase.=[Wx/org/nvca/SPA/Form/Doc_v01.md]

NDA.=[Wx/com/cooleygo/US/NDA/Form/Doc_v01.md]

and someone else can say:

NVCA.SPA.=[Wx/org/nvca/SPA/Form/Doc_v01.md]

Cooley.NDA.=[Wx/com/cooleygo/US/NDA/Form/Doc_v01.md]

I can make my doc with {SharePurchase.Doc} and they can do it with {NVCA.SPA.Doc}. I can get just the Cooley Miscellaneous section with {NDA.Misc.Sec}.

File system

The place where there is, more or less, exclusivity is in naming files. I say more or less because you can use aliases (even as part of the graph) but its better to nail this stuff down. The "solution" that looks workable - and a big improvement on the past - is to organize files in folders based on their authors - either web domain or Github repo.

Of course, all this may become less of an issue when the text is integrated into a P2P transaction system such as blockchain. But because of the familiarity of people (notably lawyers) with files in folders, there is some virtue in organizing materials this way. This is also common in the coding community, so a time-tested idea.

[HazardJ]

One area of naming could use particular attention because there must be a lot of really good knowledge and infrastructure already. Information about persons and about places. I've improvised naming schemes for both those, but they are improvised. There must be mature systems for persons and certain are mature systems for places.

[HazardJ]

U/id/tw/ - testing