README.adoc

iSAQB Advanced Level curriculum for CLOUDINFRA - Infrastructure, Container and Cloud Native

Status

This is copyrighted work.

Content

This repository contains a template for iSAQB Advanced Level curricula in AsciiDoc. This repository contains the iSAQB Advanced Level curriculum for CLOUDINFRA - Infrastructure, Container and Cloud Native in AsciiDoc.

How to contribute or participate

Create an issue, a merge- or pull-request

How to work with the curriculum

1. Clone the repository - including the submodule:

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

2. Build the project with gradle (you need a locally installed JDK) via ./gradlew buildDocs.

3. 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