Template for iSAQB Advanced Level Curricula

Status

Content

This repository contains the curriculum for the iSAQB Advanced Level DDD in AsciiDoc. It is maintained by its curators.

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 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):

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, install a JDK
Build the project with 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

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?

ℹ️	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:

   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:

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

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.

mattes3/curriculum-ddd