isaqb-org/curriculum-ddd

= Template for https://isaqb.org[iSAQB] Advanced Level Curricula

:toc: :toc-placement!:

ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

== Status image:https://github.com/isaqb-org/curriculum-ddd/workflows/CI - Releases and Main/badge.svg?branch=main["CI"] image:https://img.shields.io/github/last-commit/isaqb-org/curriculum-ddd/main.svg["Last commit"] image:https://img.shields.io/github/contributors/isaqb-org/curriculum-ddd.svg["Contributors",link="https://github.com/isaqb-org/curriculum-ddd/graphs/contributors"] image:https://img.shields.io/github/issues/isaqb-org/curriculum-ddd.svg["Issues",link="https://github.com/isaqb-org/curriculum-ddd/issues"] image:https://img.shields.io/github/issues-closed/isaqb-org/curriculum-ddd.svg["Issues closed",link="https://github.com/isaqb-org/curriculum-ddd/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+"]

This is <<copyrighted,copyrighted work>>.

== Content This repository contains the curriculum for the https://www.isaqb.org/de/zertifizierungen/zertifizierungen-uebersicht/cpsa-advanced-level/ddd-domain-driven-design/#faqs[iSAQB Advanced Level DDD] in AsciiDoc. It is maintained by its curators.

toc::[]

== How to contribute or participate We publish our curricula on Github to enable everyone to contribute and make suggestions how to evolve the software architecture education. To do this you can create an issue or a pull-request to propose additions or changes.

If you are not familiar with Asciidoc, yet, the https://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writer's Guide] is good first place to visit. This guide will also be a great companion during your work with this repository.

== How to work with this curriculum

. Either click on "Clone" in the GitHub UI or Clone the repository - including the submodule - via your git command line interface (CLI): +

[source,shell]

Via SSH: git clone git@github.com:isaqb-org/curriculum-ddd.git --recursive

Via HTTPS: git clone https://github.com/isaqb-org/curriculum-ddd.git --recursive

-- . If you don't have Java installed, https://openjdk.java.net/projects/jdk/[install a JDK] . Build the project with http://www.gradle.com[gradle] via the shell command ./gradlew buildDocs (NOTE: the java executable must be on your PATH for gradle to work properly) . Once the "BUILD SUCCESSFUL" is show, you can review the created files in the subdirectory ./build/index.html

== How to make changes to the iSAQB Advanced Level Curriculum with AsciiDoc

=== Requirements and (our) solutions

[cols="1,2a",options="header"] |=== |Requirement |Solution

|Visually appealing pdf output |We created an iSAQB pdf theme, located under the /style directory. The original is maintained in the adoc2pdf repository.

|Multiple people contribute content, review and comment |highly modularized content: Small chunks, like learning-goals or subsections, are contained in their own asciidoc-files.

|Multiple languages, at least EN and DE (i18n) |Every piece of text is enclosed in tags like tag::EN[]. The build process collects all parts for the desired language.

|Simple conversion from asciidoc to pdf (and html) |There is currently one option available:

Gradle based build, requiring a local Java runtime. |===

=== How to organize files?

NOTE: This repository relies on a specific file structure. In the following we explain the background of this structure, so you extend it if necessary.

==== Prerequisite: You understand AsciiDoc include You should know some details about the AsciiDoc include statement.

If the Asciidoctor processor encounters a statement like the one below:

[source,asciidoc]

include::directory/file.adoc[]

It will replace this include statement with the contents of file.adoc. That's easy and straightforward.

=== Content and Structure files As we are writing i18n we need to strictly distiguish between two kind of files:

content files, they contain text, tables or diagrams that shall be included in the output.
structure files, containing only include-statements, configuration information. Structure files include both content-files and other structure files.

For content files, specific parts will be included via the tag-syntax described above. For that purpose we define a variable named include_configuration in the file config/setup.adoc.

== How to create the final documents

Prerequisite: You need a Java Runtime(tm) installed. See above

You build the output documents with gradle. That will produce both pdf and html output in German (DE) and English (EN), unless you modify the configuration.

In case you want to change that, adjust the following part of build.gradle:

[source,groovy]

task buildDocs { group 'Documentation' description 'Grouping task for generating all languages in several formats' dependsOn "renderDE", "renderEN" }

In the task "renderDE", certain attributes (aka variables) are defined that configure the corresponding output.

=== How to release a new version of the curriculum

The automation and workflows in this repository trigger on every commit. If you want to create a new release of the curriculum, create a new tag in the git repository and push it to Github. TBC.

== Additional translations/languages include::docs-ext/EXTERNAL_DOCUMENTS_README.adoc[]

== Maintainers

This repository is currently maintained by Carola Lilienthal, Benjamin Wolf, and Alexander Heusingfeld. It was forked from https://github.com/isaqb-org/curriculum-template, so the contributors of that project basically contributed to this one, too.