Updated Introduction > Key Concepts

docs/accordproject-concepts.md

@@ -5,31 +5,31 @@ title: Key Concepts
 
 ## What is an Accord Project Template?
 
-An Accord Project template ties legal text (for a clause or contract) to computer code. It is composed of three elements: 
+An Accord Project template ties legal text to computer code. It is composed of three elements:
 
-- **The Template Text**: the natural language of the template
-- **The Template Model**: the data model that backs the template 
-- **The Template Logic**: the executable business logic for the template
+- **Template Text**: the natural language of the template
+- **Template Model**: the data model that backs the template
+- **Template Logic**: the executable business logic for the template
 
 ![Accord Project Template](assets/020/template.png)
 
-When combined these three elements allow templates to be edited, validated, verified, and then executed on any computer platform (on your own machine, on a Cloud platform, on Blockchain, etc).
+The three components (Text - Model - Logic) can also be intuitively understood as a **progression**, from _human-readable_ legal text to _machine-readable_ code. When combined these three elements allow templates to be edited, validated, verified, and then executed on any computer platform (on your own machine, on a Cloud platform, on Blockchain, etc).
 
-> Note that we use the computing term 'execution' here, which means run by a computer. This is distinct from the legal term 'execution' which usually refers to the process of signing an agreement.
+> Note that the computing term 'execution' is used here, which means run by a computer. This is distinct from the legal term 'execution', which usually refers to the process of signing an agreement.
 
 ### Cicero
 
-The main software implementation for the Accord Project is called [Cicero](https://github.com/accordproject/cicero). It allows users of the accord project to create and manipulate software templates which tie together all three components in the triangle above (i.e., the text, model and logic).
+The main software implementation for the Accord Project is called [Cicero](https://github.com/accordproject/cicero). It defines the structure of natural language templates, bound to a data model, that can be executed using request/response JSON messages. By doing this, Cicero allows users to create and manipulate software templates which tie together all three components in the template triangle (i.e., the text, model and logic).
 
-_More information about how to install Cicero and get started with Accord project templates can be found in the [Installation](accordproject-installation) Section of this documentation._
+_More information about how to install Cicero and get started with Accord Project templates can be found in the [Installation](started-installation) Section of this documentation._
 
 ## Template Text
 
 ![Template Text](assets/020/template_text.png)
 
-The template text is the natural language of the clause or contract. It can include markup to indicate variables (or parameters) for that template.
+The template text is the natural language of the clause or contract. It can include markup to indicate variables (or parameters) for that template. Both the model, which reflects the data referred to in the text, and the logic, which reflects the business logic in the text, will be explained in future sections.
 
-he following shows the text of an acceptance of delivery clause.
+The following shows the text of an **Acceptance of Delivery** clause.
 
 ```tem
 ## Acceptance of Delivery.
@@ -54,9 +54,9 @@ obligations under this agreement, detailed in {{attachment}}, attached
 to this agreement.
 ```
 
-The text is written in plain English with variables between `{{` and `}}` and highlighted in blue. Using variables is useful so the same template can be used in different agreements by simply replacing them by different values.
+The text is written in plain English, with variables between `{{` and `}}` and highlighted in blue. Using variables is useful so the same template can be used in different agreements by replacing them with different values.
 
-For instance, the following show the same acceptance of delivery clause where the `shipper` is `"Party A"`, the `receiver` is `"Party B"`, the `deliverable` is `"Widgets"`, etc.
+For instance, the following show the same **Acceptance of Delivery** clause where the `shipper` is `"Party A"`, the `receiver` is `"Party B"`, the `deliverable` is `"Widgets"`, etc.
 
 ```md
 ## Acceptance of Delivery.
@@ -83,7 +83,7 @@ to this agreement.
 
 ### CiceroMark
 
-CiceroMark is the markup format in which the text for Accord Project templates is written. It defines notations (such as the `{{` and `}}` notation for variables that we saw in the acceptance of delivery clause above) which allows a computer to make sense of your templates.
+CiceroMark is the markup format in which the text for Accord Project templates is written. It defines notations (such as the `{{` and `}}` notation for variables used in the **Acceptance of Delivery** clause) which allows a computer to make sense of your templates.
 
 It also provides the ability to specify the document structure (e.g., headings, lists), to highlight certain terms (e.g., in bold or italics), to indicate text which is optional in the agreement, and more.
 
@@ -93,39 +93,84 @@ _More information about the Accord Project markup can be found in the [CiceroMar
 
 ![Template Model](assets/020/template_model.png)
 
-Compared to a standard document template (e.g., in Word or pdf), Accord Project templates associate a _model_ to the natural language text. The model lets you categorize variables (is it a number, a monetary amount, a date, a reference to a business or organization, etc.). This model is crucial in that it allows the computer to make sense of the information contained in your template.
+Unlike a standard document template (e.g., in Word or pdf), Accord Project templates associate a _model_ to the natural language text. The model acts as a bridge between the text and logic; it gives the users an overview of the components, as well as the traits of different components.
 
-The following screenshot shows the model for the acceptance of delivery clause above.
+The model lets you categorize variables (is it a number, a monetary amount, a date, a reference to a business or organization, etc.). This model is crucial, because it allows the computer to make sense of the information contained in your template.
 
-![Example Model](/img/model-vscode.png)
+The following shows the model for the **Acceptance of Delivery** clause.
 
-Thanks to that model, the computer now knows that the `shipper` variable (`"Party A"` in the example above) contains a reference to an `Organization`, that variable `receiver` (`"Party B"` in the example above) also contains a reference to an Organization, that variable `deliverable` (`"Widgets"` in the example above) can contain any text description, etc.
+```ergo
+/* The template model */
+asset AcceptanceOfDeliveryClause extends AccordClause {
+
+  /** the shipper of the goods*/
+  --> Organization shipper
+
+  /** the receiver of the goods */
+  --> Organization receiver
+
+  /** what are we delivering? */
+  o String deliverable
+
+  /* how long does the receiver have to inspect the goods? */
+  o Integer businessDays
+
+  /** additional information */
+  o String attachment
+}
+```
+
+Thanks to the model, the computer now knows that the `shipper` variable (`"Party A"` in the example) and the `receiver` variable (`"Party B"` in the example) are both `Organization` types; that variable `businessDays` (`10` in the example) is an `Integer` type; and that variable `deliverable` (`"Widgets"` in the example) is a `String` type, and can contain any text description.
 
 ### Concerto
 
-Concerto is the modeling language which is used to describe the information used in Accord Project templates. Concerto offers modern modeling capabilities including support: for nested or optional data structures, enumerations, relationships, object-oriented style inheritance, and more.
+Concerto is the modeling language which is used to describe the information used in Accord Project templates. Concerto offers modern modeling capabilities including support for nested or optional data structures, enumerations, relationships, object-oriented style inheritance, and more.
 
-_More information about Concerto can be found in the [Concerto Modeling](model-concerto) Section of this documentation._
+_More information about Concerto can be found in the [Concerto Modeling](model-concerto) section of this documentation._
 
 ## Template Logic
 
 ![Template Logic](assets/020/template_logic.png)
 
-While the combination of text and model already sets Accord Project template apart from a more traditional document format, the logic is what allows templates to really _come alive_. The logic allows a developer to associate _behavior_ to the template (specify what happens when a delivery is received late, check conditions for payment, automate interest rate calculations, determine if there has been a breach of contract, etc).
-
-The following screenshot shows the logic for the acceptance of delivery clause above.
-
-![Example Logic](/img/ergo-vscode.png)
+While the combination of text and model already sets Accord Project templates apart from a more traditional document format, the logic is what allows templates to really _come alive_. The logic allows a developer to associate _behavior_ to the template (specify what happens when a delivery is received late, check conditions for payment, automate interest rate calculations, determine if there has been a breach of contract, etc).
+
+The following shows the logic for the **Acceptance of Delivery** clause.
+
+```ergo
+contract AcceptanceOfDelivery over AcceptanceOfDeliveryClause {
+  clause acceptanceofdelivery(request : InspectDeliverable) : InspectionResponse {
+
+		let received = request.deliverableReceivedAt;
+    enforce isBefore(received,now()) else
+      throw ErgoErrorResponse{ message : "Transaction time is before the deliverable date." }
+    ;
+
+    let status =
+      if isAfter(now(), addDuration(received, Duration{ amount: contract.businessDays, unit: "days"}))
+      then "OUTSIDE_INSPECTION_PERIOD"
+      else if request.inspectionPassed
+      then "PASSED_TESTING"
+      else "FAILED_TESTING"
+    ;
+    return InspectionResponse{
+      status : status,
+      shipper : contract.shipper,
+      receiver : contract.receiver
+    }
+  }
+}
+```
 
-That logic specify what conditions should be met for a delivery to be accepted (checking whether the delivery is timely or not, has a mandatory inspection for that delivery occurred or not, etc).
+The logic specifies what conditions should be met for a delivery to be accepted. The code checks whether delivery has already been made; whether the acceptance is timely, within the specified inspection date; and whether the inspection has passed or not.
 
 ### Ergo
 
-Ergo is the programming language which is used to capture the contractual logic in Accord Project templates. Since it is important that a developer and a lawyer can together agree that clauses in a computable legal contract have the same semantics as the equivalent computer code, Ergo is intended to be accessible to lawyers who create the corresponding prose for those computable legal contracts.
+Ergo is the programming language which is used to capture the contractual logic in Accord Project templates. Ergo is specifically designed for legal agreements. Since it is important that a developer and a lawyer can together agree that clauses in a computable legal contract have the same semantics as the equivalent computer code, Ergo is intended to be accessible to lawyers who create the corresponding prose for those computable legal contracts.
 
 _More information about Ergo can be found in the [Ergo Logic](logic-ergo) Section of this documentation._
 
 ## What next?
 
-Try Accord Project for yourself, either online or by installing Cicero. Find links to sample templates and other resources in the rest of this documentation.
+Try Accord Project for yourself, either [online](tutorial-latedelivery), using template studio, or by [installing Cicero](started-installation).
 
+Find links to [sample templates](started-resources) and other resources in the rest of this documentation.

docs/accordproject-developers.md

@@ -3,4 +3,22 @@ id: accordproject-developers
 title: For Developers
 ---
 
-**TBD**
+## Why is the Accord Project relevant for developers?
+The Accord Project provides a universal format for smart legal contracts, and this format is embodied in a variety of open source projects that comprise the Accord Project technology stack. Input from developers are crucial for the Accord Project.
+
+Developers can contribute by converting legal text into corresponding computer code, creating Accord Project templates to be used by lawyers and businesses. In addition, developers can provide input on the development of the technology stack components: language, models, templating, and other tools.
+
+If this interests you, please visit our [Technology Working Group](https://www.accordproject.org/working-groups/technology) page, and join our [slack channel](https://accord-project-slack-signup.herokuapp.com/)!
+
+
+## How to navigate this documentation?
+
+If you want to author, validate, and run Accord Project templates _locally_, please visit our [Install Cicero](https://docs.accordproject.org/docs/next/started-installation.html) page for instructions.
+
+If you are new to the Accord Project, please read the [Key Concepts](accordproject-concepts) page. This will allow you to understand the three components of a template (text, model, and logic) and how they work together. If you want some guidance on creating your first template, please see [Authoring in Template Studio](tutorial-latedelivery) for a step-by-step guide on how to create your first template.
+
+If you want to dive into our technology stack, you can find more information about:
+- Software implementation: [Cicero](https://github.com/accordproject/cicero)
+- Template text: [Cicero Markup](markup-cicero)
+- Template model: [Concerto Modeling](model-concerto)
+- Template logic: [Ergo Logic](logic-ergo)

docs/accordproject-lawyers.md

@@ -0,0 +1,21 @@
+---
+id: accordproject-lawyers
+title: For Lawyers
+---
+
+## Why is the Accord Project relevant for lawyers?
+
+Even the best code would be useless if it does not meet industry needs and requirements, so input from the legal community to steer the direction of smart legal contract technology is crucial. By creating templates for contract clauses or reviewing templates, lawyers can **influence** the direction of the Accord Project. In addition, feedback using domain-specific expertise can enhance the value and usability of the Accord Project templates to users.
+
+If this interests you, please visit our [Lifecycle and Industry Working Groups](https://www.accordproject.org/liwg) page for more information.
+
+As an individual, contributing to the Accord Project would be a great opportunity to **learn** about smart legal contracts. Through the Accord Project, you can understand the foundations of open source technologies and learn how to develop smart agreements.
+
+If your organization wants to become a member of the Accord Project, please join our community [here](https://www.accordproject.org/membership).
+
+
+## How to navigate this documentation?
+
+If you are new to the Accord Project, the best place to start is our [Online Tour](started-studio). This video is a great introduction to the key concepts behind the Accord Project technology. If you want to read more about the template model, please read the [Key Concepts](accordproject-concepts) page. This will allow you to understand the three components of a template (text, model, and logic) and how they work together.
+
+If you want to create a template yourself, please see [Authoring in Template Studio](tutorial-latedelivery) for a step-by-step guide on how to create your first template. The tutorial will provide an accessible starting point for those without significant development experience to begin building smart legal contracts using the Accord Project technology.

docs/accordproject.md

@@ -3,11 +3,33 @@ id: accordproject
 title: For Business
 ---
 
-## What is Accord Project?
+## What is the Accord Project?
 
-Accord Project is an open source, non-profit, initiative aimed at transforming contract management and contract automation by digitizing contracts.
+Accord Project is an open source, non-profit initiative aimed at transforming contract management and contract automation by digitizing contracts.
 
-Accord Project defines a notion of legal template with associated computing logic which is expressive, open-source, and portable. 
+The Accord Project defines a notion of a legal template with associated computing logic which is expressive, open-source, and portable. Accord Project templates are similar to a clause or contract template in any document format, but they can be read, interpreted, and run by a computer.
 
-Accord project templates are similar to a clause or contract template in any document format, but they can be read, interpreted, and run by a computer.
+The goal of the Accord Project is to provide a common, standardized format for smart legal contracts.
 
+## What is a Smart Legal Contract?
+
+A Smart Legal Contract is a human-readable and machine-readable agreement that is digital, consisting of natural language and executable business logic.
+
+- The machine-readable nature of the document enables it to be interpreted and executed by computers. It is this attribute that makes the document “smart”.
+- The human-readable nature of the document ensures that signatories, lawyers, contracting parties and others are able to understand the contract as well as enabling that contracts are able to consist of a hybrid of both ‘smart’ and ‘non-smart’ components.
+    - For example, a smart legal contract may consist of a smart payment clause with all of the other provisions of the contract (Definitions, Jurisdiction clause, Force Majeure clause, ...) being documented solely in regular human-readable text.
+
+### What are the Benefits?
+It enables a contract to be easily searched, analyzed, queried, and understood. Using a modeled version of a contract, it is possible to extract a host of valuable data about a contract or series of contracts from certain data points (e.g. variables and their values).
+
+In addition, it provides the necessary structure to enable contracts to be “smart” by adding executable logic. Without a structured data model it is difficult to ensure all of the necessary data is present in the contract, the data is valid, and that the logic and the text reflect one another.
+
+For more information about smart legal contracts, and how they are different from "smart contracts", please visit the [Accord Project FAQ Page](https://www.accordproject.org/frequently-asked-questions).
+
+## Why is the Accord Project relevant for Businesses?
+
+Contracting is undergoing a digital transformation driven by a need to deliver customer-centric legal and business solutions faster, and at lower cost. This imperative is fueling the adoption of a broad range of new technologies to improve the efficiency of drafting, managing, and executing legal contracting operations; the Accord Project is proud to be part of that movement.
+
+In addition, contributions from businesses are crucial for the development of the Accord Project. The expertise of stakeholders, such as business professionals and attorneys, is invaluable in improving the functionality and content of the Accord Project's codebase and specifications, to ensure that the templates meet real-world business requirements.
+
+If this interests you, please visit our [Lifecycle and Industry Working Groups](https://www.accordproject.org/liwg) page for more information.