Add intial documents

README.md

@@ -1,3 +1,3 @@
 # collaboration
 
-How we want to collaborate. Processes, concepts, tools, howtos
+How we want to collaborate. Processes, concepts, tools, howto's.

antora-playbook.yml

@@ -0,0 +1,38 @@
+
+---
+site:
+  title: collaboration
+  # url: https://itemsdb.matthiess.it
+  start_page: collaboration::README.adoc
+
+
+output:
+  clean: true
+  dir: build/html
+
+
+content:
+  sources:
+    - url: /home/f4m8/prj/code.matthiess.de/collaboration
+      worktrees: true
+
+# asciidoc:
+#   sourcemap: true
+
+#   # extensions:
+#   # - asciidoctor-kroki
+
+#   # attributes:
+#   #   kroki-fetch-diagram: true
+
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+
+runtime:
+  log:
+    format: pretty
+  fetch: true
+
+# code: language=yaml

antora.yml

@@ -0,0 +1,11 @@
+---
+
+name: collaboration
+title: Collaboration
+version: 0.1
+prerelease: -rc.1
+
+nav:
+  - modules/ROOT/nav.adoc
+
+# code: language:yaml

modules/ROOT/nav.adoc

@@ -0,0 +1 @@
+* xref:README.adoc[]

modules/ROOT/pages/README.adoc

@@ -0,0 +1,19 @@
+= Collaboration
+:navtitle: Why we describe this stuff?!?
+
+If we want to collaborate in a productive manner, we have to answer some
+questions how to interacting with each other. This is not only a matter of a
+communication style but also the how and why of using tools and frameworks.
+
+* Which processes, tools and frameworks we use to collaborated?
+* Why we like to do ist this way?
+* Why we track which part like code or decisions?
+** How we track code?
+** How we track decisions?
+
+Some of this questions seems to easy to answer, but this has to be answered and
+fixed in a documentation.
+
+For all this topics is this documentation for.
+
+

modules/documentation/images/vscodium-logo.svg

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0" y="0" width="100" height="100" viewBox="0, 0, 100, 100">
+  <defs>
+    <linearGradient id="Gradient_1" gradientUnits="userSpaceOnUse" x1="199.997" y1="214.302" x2="296.665" y2="307.573" gradientTransform="matrix(1, 0, 0, 1, -200, -213)">
+      <stop offset="0" stop-color="#62A0EA"/>
+      <stop offset="1" stop-color="#1A5FB4"/>
+    </linearGradient>
+  </defs>
+  <g id="Layer_1">
+    <path d="M48.26,2.274 C45.406,4.105 44.583,7.898 46.422,10.742 C56.531,26.397 58.917,38.205 57.882,48.553 C53.698,68.369 44.603,72.389 36.655,72.389 C28.895,72.389 30.973,59.618 36.806,55.88 C40.288,53.706 44.748,52.293 48.171,52.293 C51.563,52.293 54.313,49.552 54.313,46.17 C54.313,42.787 51.563,40.046 48.171,40.046 C44.173,40.046 40.251,40.886 36.59,42.316 C37.338,38.787 37.614,34.973 36.647,30.919 C35.179,24.763 30.953,18.883 23.615,13.183 C22.33,12.183 20.7,11.734 19.083,11.934 C17.466,12.134 15.995,12.966 14.994,14.248 C12.912,16.918 13.394,20.766 16.072,22.843 C22.05,27.486 24.024,30.923 24.699,33.752 C25.374,36.581 24.831,39.616 23.475,43.786 C21.742,49.406 19.73,54.423 18.848,59.234 C18.414,61.602 18.377,64.179 18.265,66.238 C13.96,62.042 12.275,56.502 12.275,48.407 C12.274,45.025 9.524,42.283 6.133,42.284 C2.744,42.287 -0.002,45.027 -0.003,48.407 C-0.003,59.463 3.23,69.983 11.895,77.001 C19.739,84.474 39.686,81.712 39.686,93.709 C39.686,97.095 44.642,98.743 48.033,98.743 C51.511,98.743 55.888,96.418 55.888,93.709 C55.888,80.097 70.233,71.824 93.848,71.86 C97.24,71.865 99.992,69.126 99.997,65.744 C100.003,62.361 97.259,59.614 93.867,59.608 C92.252,59.606 90.678,59.661 89.126,59.753 C91.766,53.544 92.937,46.708 92.695,39.324 C92.583,35.943 89.745,33.293 86.356,33.403 C82.963,33.513 80.305,36.346 80.416,39.729 C80.736,49.397 80.374,58.03 73.171,62.581 C71.123,63.874 68.742,64.996 66.484,64.996 C68.237,60.228 69.561,55.195 70.103,49.77 C70.449,46.308 70.486,42.195 70.091,39 C69.478,34.05 68.738,28.436 70.617,24.207 C72.305,20.565 76.087,19.04 81.64,19.04 C85.029,19.037 87.775,16.296 87.776,12.917 C87.778,9.534 85.031,6.79 81.64,6.787 C73.388,6.787 67.133,11.13 63.587,16.377 C61.733,12.417 59.475,8.336 56.747,4.112 C55.866,2.747 54.478,1.788 52.887,1.443 C52.099,1.272 51.285,1.257 50.491,1.399 C49.697,1.542 48.939,1.839 48.26,2.274 z" fill="url(#Gradient_1)" id="path6008"/>
+  </g>
+</svg>

modules/documentation/pages/_asciidoc-urls.adoc

@@ -0,0 +1,4 @@
+:asciidoc-home: https://asciidoc.org/
+:asciidoc-lang: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang
+:asciidoc-wg: https://asciidoc-wg.eclipse.org/
+:eclipse-foundation: https://www.eclipse.org/

modules/documentation/pages/_ide.adoc

@@ -0,0 +1,3 @@
+:vscode: https://code.visualstudio.com/[Microsoft Visual Studio Code]
+:vsc: https://code.visualstudio.com/[VScode]
+:vscodium: https://vscodium.com/[VSCodium]

modules/documentation/pages/_markdown-urls.adoc

@@ -0,0 +1,4 @@
+
+:markdown-home: https://www.markdownguide.org/
+:markdown-basic: https://www.markdownguide.org/basic-syntax/
+:markdown-extended: https://www.markdownguide.org/extended-syntax/

modules/documentation/pages/_vsc-extensions.adoc

@@ -0,0 +1,2 @@
+:vsc-asciidoctor: https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[VSCode extension asciidoctor.asciidoctor-vscode]
+:vsc-plantuml: https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml[VSCode extension jebbs.plantuml]

modules/documentation/pages/index.adoc

@@ -0,0 +1,83 @@
+== Documentation
+
+We want to write the documentation inside of our daily toolset and processes.
+The already open IDE with git and the review process gives us the opportunity to
+concentrate on the content.
+
+Besides the tools and processes we need an understanding of the concept of our
+documentation.
+
+[quote,David Laing,The Grand Unified Theory of Documentation]
+There is a secret that needs to be understood in order to write good software
+documentation: there isn’t one thing called documentation, there are four.
+They are: tutorials, how-to guides, technical reference and explanation. They
+represent four different purposes or functions, and require four different
+approaches to their creation. Understanding the implications of this will help
+improve most documentation - often immensely.
+
+:divio-com-doc-system: https://docs.divio.com/documentation-system/
+
+image::four-documentation-types-divia.com.png[]
+
+source: {divio-com-doc-system}
+
+
+=== Markup language of the documentation
+
+==== Markdown markup
+
+include::_markdown-urls.adoc[]
+
+image::markdown-logo.png[135,88,role="related thumb right"]
+
+The widely used {markdown-home}[Markdown markup] has some flaw and disadvantages:
+
+* A {markdown-basic}[base markdown markup description] hardly used as standard
+* Several {markdown-extended}["flavors"] which tries to solve some of the
+  missing parts in the base description
+
+
+
+==== Asciidoc markup
+
+include::_asciidoc-urls.adoc[]
+
+image::AsciiDoc-icon-color.png[88,88,role="related thumb right"]
+
+The {asciidoc-home}[Asciidoc markup] has a well defined
+{asciidoc-lang}[specification] which is developd by a {asciidoc-wg}[working
+group] under the umbrella of the {eclipse-foundation}[Eclipse Foundation].
+
+To convert the Asciidoc markup into several formats and targets the
+{asciidoctor} framework is used. There exist the processors:
+
+* Ruby
+* Java
+* Javascript
+
+=== Markup toolset
+
+include::_ide.adoc[]
+
+image::Asciidoctor-icon.png[88,88,role="related thumb right"]
+
+We need a toolset to write the documentation with a proper preview function.
+This could be solved within your preferred IDE or editor.
+
+If not already used you could give this a try:
+
+* {vscodium} (Free/Libre Open Source Software Binaries of VS Code)
+
+image::vscodium-logo.svg[88,88,role="related thumb right"]
+
+* {vscode}
+
+image::ms-vscode.png[88,88,role="related thumb right"]
+
+With that in place you should install this extension to support writing the
+asciidoc markup:
+
+include::_vsc-extensions.adoc[]
+
+* {vsc-asciidoctor}
+* {vsc-plantuml}