Merge pull request #1491 from AmpersandTarski/Specflowdocs

Documentatie aangevuld tbv SpecFlow testen

README.md

@@ -9,6 +9,4 @@ Check out the [release notes](https://github.com/AmpersandTarski/Ampersand/blob/
 
 ## Documentation
 
-We are currently in a process to change the way we publish our documentation. The old site can be found [here](https://ampersandtarski.gitbook.io/documentation/). It is still easier to navigate. The new site can be found [here](https://ampersandtarski.github.io/docs/Ampersand/). It contains all documentation of several repositories in a single place. We are still [working](https://github.com/AmpersandTarski/Ampersand/issues/1315) on structuring it. 
-
-The old site does not contain the documentation specific for developers of Ampersand. That can be found as [documentation for the developers of ampersand](https://ampersandtarski.gitbook.io/the-tools-we-use-for-ampersand/).
+We are currently in a process to change the way we publish our documentation. The old site can be found [here](https://ampersandtarski.gitbook.io/documentation/). The new site can be found [here](https://ampersandtarski.github.io/docs/Ampersand/). It features full-text search and it contains all documentation of several repositories in a single place. We are still [working](https://github.com/AmpersandTarski/Ampersand/issues/1315) on structuring it. 

ReleaseNotes.md

@@ -1,5 +1,7 @@
 # Release notes of Ampersand
 
+## Unreleased
+
 ## v5.1.2 (11 august 2024)
 - [Issue #1381](https://github.com/AmpersandTarski/Ampersand/issues/1381) Bugfixes for support for new Angular frontend
 - Drop support for old AngularJS frontend

docs/future-plans.md

@@ -25,13 +25,42 @@ One purpose of Ampersand is to generate a web-application. Currently, the genera
 
 The architecture is explained in more detail in [this chapter](./reference-material/architecture-of-an-ampersand-application).
 
+## Low-code Ampersand
+   The current RAP tool requires users to write Ampersand code in Ampersand syntax.
+   The Atlas, which is part of RAP, then shows all concepts, relations and rules in a nice interface.
+   We want to make the atlas interactive, so that users can manage their specifications directly in the Atlas instead of writing Ampersand code.
+   We want them to deploy their specification directly from the Atlas.
+
+### Purpose
+   To make Ampersand more accessible to a wider audience, we want to create a low-code    version of Ampersand.
+
+## Schema-Changing Data Migration
+   Ampersand compiles and deploys a specification into a functional information system.
+   However, it lacks support for data migration, so it is less useful for maintaining information systems.
+   Only if an upgrade can be done by re-generating the entire system, Ampersand is useful.
+   But when existing production data needs to be preserved, re-generation is not always an option.
+   Especially for increments that alter the system's schema in production,
+   developers must manually migrate the data, which is error-prone and time-consuming.
+   This can inhibit a steady pace of releases and it inevitably involves down-time.
+   Consequently, schema-changing data migrations often face challenges, leading developers to resort to manual migration or employ workarounds.
+
+### Purpose
+   To address this issue, we want Ampersand to support schema-changing data migration.
+   We aim to generate migration scripts for automating the migration process, as described in Joosten\&Joosten, Data Migration under a Changing Schema in Ampersand, in: Proceedings of Relational and Algebraic Methods in Computer Science (RAMiCS), Prague, 2024.
+
+![](./assets/migration_system_deployed.png)
+
+   The overarching challenge is to preserve the business semantics of data amidst schema changes, under the condition of zero downtime.
+   We plan to do this as a [project](https://github.com/orgs/AmpersandTarski/projects/12?pane=info) in the A-team.
+   By solving this problem we can increase the frequency of releases in the software process.
 
 ## NoSQL storage
 The current architecture builds on an SQL database, using MariaDB (formerly known as MySQL)
 Instead of storing data to an SQL database only, we want to other types of databases to work with Ampersand as well.
 Especially NoSQL databases \(e.g. triple stores, graph databases, persistent event streaming\) seem very suited for Ampersand.
 
 This enhancement will gain traction when some party (e.g. a database vendor) sees benefits in this research and is willing to sponsor it (either in kind or in cash).
+
 ### Purpose
 The problem is that modern persistent stores come in many sorts and shapes.
 There are triple stores, graph databases, persistent event streaming, to name but a few technologies that have conquered the landscap of persistent data. We want Ampersand to link up with such technologies to serve a wider spectrum of problems.

docs/guides/frequently-asked-questions.md

@@ -6,9 +6,16 @@ So don't hesitate to ask.
 
 Some questions in this page do not have an answer yet. Please consider that as ongoing work and bear with us...
 
+##  Documentation
+* How can I contribute to the documentation of Ampersand?
+
+  *Answer*
+
 ##  Maintenance
 * How can I inspect the database underneath an Ampersand application?
 
+  *Answer*: You can deploy PhpMyAdmin alongside your Ampersand application, to inspect the database underneath your Ampersand application. Do a full-text search to `PhpMyAdmin` in the [Ampersand documentation](https://ampersandtarski.github.io) to find out how to do this.
+
 ## Deployment
 * [How can I deploy an Ampersand application on my laptop?](installing-ampersand.md)
 * [How can I deploy an Ampersand application on a virual machine (i.e. a server)](installing-ampersand.md)
@@ -26,4 +33,10 @@ Some questions in this page do not have an answer yet. Please consider that as o
 * How can I change the documentation of Ampersand?
 
 ##  General interest
-* Why is [declarative](../conceptual/why-declarative.md) a useful property?
+* Why is "declarative" a useful property?
+
+  *Answer*: Ampersand is a [declarative](../conceptual/why-declarative.md) language, to enable mathematical reasoning with the terms in the language.
+
+* How can I monitor an Ampersand application in production?
+
+  *Answer*: RAP is an Ampersand application, which is monitored by Grafana and Prometheus on a Kubernetes cluster. You can take it as an example and copy the setup from the manifest files in the [RAP repository](https://github.com/AmpersandTarski/RAP).

docs/modeling/conceptual-modeling.md

@@ -1,19 +1,89 @@
-# Domain Driven Design
+# Conceptual modeling
+We use the Ampersand language to make domain models.
+A domain model is a conceptual model of a domain.
+It is a representation of the domain's concepts, relationships, and constraints. It is a way to describe the structure of a domain, the business processes that take place within it, and the rules that govern it.
+
+We use the terms "conceptual model" and "domain model" interchangeably because we will always apply this technique to a specific domain.
 
 ## Why bother?
 
 Domain modeling is used for various purposes:
 
-1. To explore unknown domains. The act of making domain models is an efficient way to familiarize yourself with a new domain and to unravel anfractuous jargon.
+1. To explore unknown domains. The act of making domain models is an efficient way to familiarize yourself with a new domain and to unravel jargon.
 2. To define the boundaries of individual services. A domain model should make these boundaries clear, to develop components as independently as possible.
 3. To avoid misunderstandings over terminology in a project with multiple stakeholders. A terminology list does not always suffice in practice. A domain model should consolidate consensus and make misunderstandings explicit and debatable before they do harm.
 4. Learning. A learner must familiarize herself with new words and specific phrases. Making a domain model improves both the speed and depth of learning.
 
-The Ampersand way of domain modeling is classic in the sense that a conceptual model is made of a domain of your choice. It differs from other approaches in specific ways:
+The Ampersand way of conceptual modeling is a traditional approach where a conceptual model is built for a chosen domain. The Ampersand approach is particularly valuable when:
+
+1. Your model needs to be interpreted by a computer to create specific useful artifacts, such as a data model, a prototype implementation, or documentation.
+2. Your model has an interpretation in natural language, which you can use to standardize and unify the language of the business.
+
+## What is a conceptual model?
+A conceptual model consists of concepts and relations that describe the language structure of a domain and comprises the constraints that govern it.
+
+|     |     |     |
+| --- | --- | --- |
+| Component | Description | Example |
+| Concepts | The fundamental entities or ideas within a domain. | In an e-commerce domain, concepts might include product, customer, and order. |
+| Relations | Relations describe how concepts are related to each other. | For example, the relation `orders` can represent facts about which customer has placed which order. |
+| Language Structure | The specific vocabulary and terminology used to describe the concepts and relations. A conceptual model helps ensure consistency and clarity in how people communicate about the domain. |  |
+| Constraints | Rules that govern the behavior of the domain. They specify limitations or conditions that apply to concepts and relations. | Examples of constraints in e-commerce include a product must have a name and price, and a customer must have a unique identifier (e.g., email address). |
+
+## Example: a conceptual model in Ampersand
+A conceptual model may have many different representations. Here is an example of a conceptual model in Ampersand source code:
+```Ampersand
+CONTEXT Enrollment IN ENGLISH
+
+    RELATION takes[Student*Course]
+    RELATION isPartOf[Module*Course]
+    RELATION isEnrolledFor [Student*Module]
+
+    RULE ModuleEnrollment: isEnrolledFor |- takes;isPartOf~
+
+ENDCONTEXT
+```
+The following diagram represents the conceptual model visually. Note that this diagram does not represent the constraint:
+
+![](../assets/brokenLink.png)
+@stefjoosten, TODO: please fix this link. It was pointing to the non-existent file `../assets/CDRuleModuleEnrollment.png`
+
+The following diagram shows the conceptual model as a data model:
+
+![](../assets/TechnicalDataModel.png)
+
+Constraints are rarely visualized in graphical representations of conceptual models.
+Yet, they are an essential part of the conceptual model. They are the rules that govern the domain.
+
+## First validation
+Can your conceptual model represent facts in your domain?
+This is your first step in creating a conceptual model.
+The following Ampersand code represents eight facts in the domain of enrollment:
+```Ampersand
+CONTEXT Enrollment IN ENGLISH
+
+POPULATION takes[Student*Course] CONTAINS
+[ ("Peter", "Management")
+; ("Susan", "Business IT")
+; ("John", "Business IT")
+]
+
+POPULATION isPartOf[Module*Course] CONTAINS
+[ ("Finance", "Management")
+; ("Business Rules", "Business IT")
+; ("Business Analytics", "Business IT")
+; ("IT-Governance", "Business IT")
+; ("IT-Governance", "Management")
+]
 
-1. Your model can be interpreted by a computer to create specific useful artifacts, such as a data model, a prototype implementation, or documentation;
-2. Your model has an interpretation in natural language, which you can use to calibrate and uniform the language of the business.
+ENDCONTEXT
+```
+Among others, this code represents the fact that
+Peter takes the course Management and the fact that the module IT-Governance is part of two courses: Business IT and Management.
 
+We advise strongly to invent 2-3 facts for every relation in your domain and to represent them in Ampersand code,
+to verify that your relations can represent the facts you intend them to represent
+.
 ## Steps
 
 Here is a summary of the things you do.

docs/reference-material/atoms.md

@@ -51,7 +51,7 @@ The distinction between closed and open types is relevant in the following situa
 - The full relation, `V[A*B]` is defined only if both `A` and `B` are closed.
 - An interface `INTERFACE X : e` requires that the target of `e` is closed.
 
-Violations are currently signaled at runtime, but future versions of Ampersand will signal these violations at compile time.
+Inconsistencies are currently signaled at runtime, but future versions of Ampersand will signal these violations at compile time.
 
 ## Miscellaneous
 

docs/reference-material/terms.md

@@ -240,7 +240,7 @@ The sentence: "Peter owns a MacBook and Peter does not want a MacBook." is repre
 
 ##### Natural language templates
 
-There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](https://ampersandtarski.gitbook.io/documentation/~/drafts/-LKR7o8ALsxT8aQfWugs/primary/ampersands-own-language/semantics-visualized/semantics-visualized). The systematic translation is given in the following table:
+There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. The systematic translation is given in the following table:
 
 | Formally            | Natural language template |
 | ------------------- | ------------------------- |
@@ -274,7 +274,7 @@ The sentence "A _contract with a blue label is stored in cabinet 42_." can be re
 
 ##### Natural language templates
 
-There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](https://ampersandtarski.gitbook.io/documentation/~/drafts/-LKR7o8ALsxT8aQfWugs/primary/ampersands-own-language/semantics-visualized/semantics-visualized). The systematic translation is given in the following table:
+There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. The systematic translation is given in the following table:
 
 | Formally    | Natural language template                   |
 | ----------- | ------------------------------------------- |
@@ -297,7 +297,7 @@ Also assume another relation `stored[Contract*Location]`, which gives the locati
 
 ##### Natural language templates
 
-There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. For examples [click here](#semantics-visualized). The systematic translation is given in the following table:
+There is a pattern to this. A computer can generate a literal translation from the formula to natural language. However, that translation looks clumsy, verbose and elaborate. It is up to you to turn that in normal language. The systematic translation is given in the following table:
 
 | Formally     | Natural language template                                           |
 | :----------- | :------------------------------------------------------------------ |

docs/sidebar.js

@@ -33,6 +33,11 @@ module.exports = {
             type: 'doc',
             id: 'ampersand/reference-material/dictionary'
         },
+        {
+            label: 'Video tutorials',
+            type: 'doc',
+            id: 'ampersand/video-tutorials'
+        },
         {
             label: 'Meta syntax',
             type: 'doc',
@@ -112,7 +117,6 @@ module.exports = {
             items: [
                 'ampersand/guides/onboarding',
                 'ampersand/the-tools-we-use/README',
-                'ampersand/the-tools-we-use/SUMMARY',
                 'ampersand/the-tools-we-use/ampersand-language-support',
                 'ampersand/the-tools-we-use/authentication-and-access-management-with-oauth',
                 'ampersand/the-tools-we-use/automation-of-releasing-ci-cd/README',
@@ -131,16 +135,8 @@ module.exports = {
                 'ampersand/the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation',
                 'ampersand/the-tools-we-use/gitbook/getting-started-with-gitbook',
                 'ampersand/the-tools-we-use/group-1/development-using-vs-code',
-                'ampersand/the-tools-we-use/installation-of-rap/README',
-                'ampersand/the-tools-we-use/installation-of-rap/deploying-ounl-rap3',
-                'ampersand/the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu',
-                'ampersand/the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop',
-                'ampersand/the-tools-we-use/installation-of-rap/deployment-configuration',
-                'ampersand/the-tools-we-use/installation-of-rap/details',
-                'ampersand/the-tools-we-use/installation-of-rap/making-docker-images',
-                'ampersand/the-tools-we-use/installation-of-rap/redeploying-rap3',
                 'ampersand/the-tools-we-use/klad',
-                'ampersand/the-tools-we-use/making-images',
+                'ampersand/the-tools-we-use/making-docker-images',
                 'ampersand/the-tools-we-use/prototype-framework',
                 'ampersand/the-tools-we-use/rap3-student',
                 'ampersand/the-tools-we-use/rap3-tutor',
@@ -158,6 +154,11 @@ module.exports = {
             type: 'doc',
             id: 'ampersand/reference-material/configuring-your-application'
         },
+        {
+            label: 'A list of all instructional videos',
+            type: 'doc',
+            id: 'ampersand/videos'
+        },
     ],
     ampersandTheorySidebar: [
         {
@@ -234,7 +235,6 @@ module.exports = {
         //     type: 'category',
         //     items: [
         //         'the-tools-we-use/README',
-        //         'the-tools-we-use/SUMMARY',
         //         'the-tools-we-use/ampersand-language-support',
         //         'the-tools-we-use/authentication-and-access-management-with-oauth',
         //         'the-tools-we-use/automation-of-releasing-ci-cd/README',
@@ -253,16 +253,7 @@ module.exports = {
         //         'the-tools-we-use/gitbook/dos-and-donts-in-ampersand-documentation',
         //         'the-tools-we-use/gitbook/getting-started-with-gitbook',
         //         'the-tools-we-use/group-1/development-using-vs-code',
-        //         'the-tools-we-use/installation-of-rap/README',
-        //         'the-tools-we-use/installation-of-rap/deploying-ounl-rap3',
-        //         'the-tools-we-use/installation-of-rap/deploying-rap3-with-azure-on-ubuntu',
-        //         'the-tools-we-use/installation-of-rap/deploying-to-your-own-laptop',
-        //         'the-tools-we-use/installation-of-rap/deployment-configuration',
-        //         'the-tools-we-use/installation-of-rap/details',
-        //         'the-tools-we-use/installation-of-rap/making-docker-images',
-        //         'the-tools-we-use/installation-of-rap/redeploying-rap3',
         //         'the-tools-we-use/klad',
-        //         'the-tools-we-use/making-images',
         //         'the-tools-we-use/prototype-framework',
         //         'the-tools-we-use/rap3-student',
         //         'the-tools-we-use/rap3-tutor',

docs/the-tools-we-use/Documentation.md

@@ -0,0 +1,3 @@
+# Documentation
+
+## How to contribute to the documentation of Ampersand