README.adoc

Template for iSAQB Advanced Level Curricula

Status

This is copyrighted work.

Content

This repository contains a template for iSAQB Advanced Level curricula in AsciiDoc.

How to contribute or participate

Create an issue, a merge- or pull-request

How to use this template

1. Either click on "Use this template" in the Github UI or Clone the repository - including the submodule:

   Via SSH:
   git clone [email protected]:isaqb-org/advanced-template.git --recursive
   
   Via HTTPS:
   git clone https://github.com/isaqb-org/advanced-template.git --recursive

2. Rename the repository to the name of your curriculum e.g. curriculum-flex

3. Rename the file /docs/advanced-template.adoc to the name of your curriculum e.g. curriculum-flex.adoc (this is later on referred to as curriculumFileName)

4. Open the file ./config/setup.adoc to adjust configuration specific to your curriculum:

   1. :curriculum-short: MODULKUERZEL: this is the abbreviation of your module. Replace MODULKUERZEL with your module name e.g. FLEX

   2. :curriculum-name: MODULNAME IN VOLLER LAENGE: the full German title of your CPSA-A module. replace "MODULNAME IN VOLLER LAENGE" with your module name e.g. "Flexible Architecture Models - Microservices und Self-Contained Systems"

   3. :curriculum-name: MODULNAME IN VOLLER LAENGE: the full English title of your CPSA-A module. replace "MODULNAME IN VOLLER LAENGE" with your module name e.g. "Flexible Architecture Models - Microservices and Self-Contained Systems"

5. Open the file build.gradle to adjust attributes specific to your curriculum:

   1. curriculumFileName: the name of the asciidoc root file of your curriculum e.g. curriculum-flex (see above! The .adoc suffix is added automatically, omit it here!)

6. Open README.adoc and replace the string curriculum-template with the name of your Github repository e.g. curriculum-flex

7. Build the project with gradle (you need a locally installed JDK 17 or higher) via ./gradlew.

8. Once the "BUILD SUCCESSFUL" is show, you can review the build result under ./build/index.html

How to write iSAQB Advanced Level Curricula 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.

---

TODO: Add explanation for keywords and general procedure when creating a new Advanced Level Curriculum.

---

How to organize files?

Prerequisite: 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.

Structure File Example

In theory, you can just use the docs/curriculum-template.adoc as is and just edit the section documents in the subdirectories. If you want to create your own file, we recommend to stick with the following:

From docs/curriculum-template.adoc (excerpts):

= Template Curriculum: CPSA Certified Professional for Software Architecture^(R)^
:doctype: book

include::config/setup.adoc[]  // // (1)

:document-version: 2020.2 // //(2)

:sectnums!: // // (3)
include::00-preamble/copyright.adoc[{include_configuration}] // // (4)

<<< // // (5)
:toc:

<<<
:sectnums!:
include::00-preamble/00-introduction.adoc[] // //(6)

1. We propose to put the asciidoc configuration in this special file (docs/config/setup.adoc).

2. You can set a version, but it may be overridden in the build process.

3. You can turn section numbering on and off (here: off).

4. This includes parts of the docs/00-preamble/copyright.adoc file.

5. The <<< will create a pagebreak in pdf files.

6. Include the whole file 00-introduction.adoc.

Suggestions

TBD.

How to build the documents

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

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.

Additional translations/languages

docs-ext/EXTERNAL_DOCUMENTS_README.adoc

Maintainers

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

Licensing and Copyright

license-copyright/LICENSE.adoc