diff --git a/README.md b/README.md index 8a28465..09c7718 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,3 @@ # collaboration -How we want to collaborate. Processes, concepts, tools, howtos \ No newline at end of file +How we want to collaborate. Processes, concepts, tools, howto's. diff --git a/antora-playbook.yml b/antora-playbook.yml new file mode 100644 index 0000000..2a3fc50 --- /dev/null +++ b/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 diff --git a/antora.yml b/antora.yml new file mode 100644 index 0000000..8899263 --- /dev/null +++ b/antora.yml @@ -0,0 +1,11 @@ +--- + +name: collaboration +title: Collaboration +version: 0.1 +prerelease: -rc.1 + +nav: + - modules/ROOT/nav.adoc + +# code: language:yaml diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc new file mode 100644 index 0000000..61b0603 --- /dev/null +++ b/modules/ROOT/nav.adoc @@ -0,0 +1 @@ +* xref:README.adoc[] diff --git a/modules/ROOT/pages/README.adoc b/modules/ROOT/pages/README.adoc new file mode 100644 index 0000000..210a3fd --- /dev/null +++ b/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. + + diff --git a/modules/documentation/images/AsciiDoc-icon-color.png b/modules/documentation/images/AsciiDoc-icon-color.png new file mode 100644 index 0000000..1cf73e2 Binary files /dev/null and b/modules/documentation/images/AsciiDoc-icon-color.png differ diff --git a/modules/documentation/images/Asciidoctor-icon.png b/modules/documentation/images/Asciidoctor-icon.png new file mode 100644 index 0000000..ab54fee Binary files /dev/null and b/modules/documentation/images/Asciidoctor-icon.png differ diff --git a/modules/documentation/images/four-documentation-types-divia.com.png b/modules/documentation/images/four-documentation-types-divia.com.png new file mode 100644 index 0000000..52d646e Binary files /dev/null and b/modules/documentation/images/four-documentation-types-divia.com.png differ diff --git a/modules/documentation/images/markdown-logo.png b/modules/documentation/images/markdown-logo.png new file mode 100644 index 0000000..e7cb537 Binary files /dev/null and b/modules/documentation/images/markdown-logo.png differ diff --git a/modules/documentation/images/ms-vscode.ico b/modules/documentation/images/ms-vscode.ico new file mode 100644 index 0000000..0be222e Binary files /dev/null and b/modules/documentation/images/ms-vscode.ico differ diff --git a/modules/documentation/images/ms-vscode.png b/modules/documentation/images/ms-vscode.png new file mode 100644 index 0000000..876cc84 Binary files /dev/null and b/modules/documentation/images/ms-vscode.png differ diff --git a/modules/documentation/images/vscodium-logo.svg b/modules/documentation/images/vscodium-logo.svg new file mode 100644 index 0000000..f6bad25 --- /dev/null +++ b/modules/documentation/images/vscodium-logo.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/modules/documentation/nav.adoc b/modules/documentation/nav.adoc new file mode 100644 index 0000000..e69de29 diff --git a/modules/documentation/pages/_asciidoc-urls.adoc b/modules/documentation/pages/_asciidoc-urls.adoc new file mode 100644 index 0000000..09d30e8 --- /dev/null +++ b/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/ diff --git a/modules/documentation/pages/_ide.adoc b/modules/documentation/pages/_ide.adoc new file mode 100644 index 0000000..bb83d59 --- /dev/null +++ b/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] diff --git a/modules/documentation/pages/_markdown-urls.adoc b/modules/documentation/pages/_markdown-urls.adoc new file mode 100644 index 0000000..da4ae5d --- /dev/null +++ b/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/ diff --git a/modules/documentation/pages/_vsc-extensions.adoc b/modules/documentation/pages/_vsc-extensions.adoc new file mode 100644 index 0000000..de36cea --- /dev/null +++ b/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] diff --git a/modules/documentation/pages/index.adoc b/modules/documentation/pages/index.adoc new file mode 100644 index 0000000..97064e9 --- /dev/null +++ b/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}