Skip to content

Latest commit

 

History

History
65 lines (55 loc) · 1.86 KB

content.adoc

File metadata and controls

65 lines (55 loc) · 1.86 KB
Raw

Content

Task

  1. create (technical) documentation in an appropriate format which should support export to PDF, HTML, Confluence

  2. the documentation should support diagrams, e.g. PlantUML or Mermaid

  3. the documentation export should be reproducible

Decision

  1. We use AsciiDoc as a technology to write the documentation in.

  2. We use git as version control system.

  3. In order to support reproducibility we establish a build process that utilizes plugins to support the targeted formats.

    1. We use maven as a build tool to execute that build process.

    2. The following plugins help us to achieve our goals:

      1. asciidoctor-maven-plugin to export to PDF and HTML

      2. asciidoc-confluence-publisher-maven-plugin to export to as many confluence instances as needed.

  4. In order to support diagrams as code we chose PlantUML over Mermaid as it seems to be more mature at the moment and also is supported by the confluence-publisher-plugin.

PlantUML

There are at least these two ways to use PlantUML in the documenation:

Include

.ASCIIDoc per Include
[plantuml,build,svg,align="center"]
....
include::../uml/build.puml[]
....
ASCIIDoc via include
link:../uml/build.puml[role=include]

Inline

.ASCIIDoc inline
[plantuml,puml,svg,align="center"]
....
@startuml
title inline
Speaker --> audience : says "It can also be done inline"
Audience --> Martin : answers "Yippie"
@enduml
....
ASCIIDoc inline
@startuml
title inline
Speaker --> Audience : says "It can also be done inline"
Audience --> Speaker : answers "Yippie"
@enduml