Page tree

Here you will find a summary of the pages in this space.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Welcome to the arc42 Confluence Template space. Here you find all you need to get started with your software architecture documentation if you want to use Confluence as your content management system. 

But you still have several ways to use arc42 with Confluence:

1) Download and install one of the templates as Confluence space

There are two flavours for each language which we call 'flat' and 'structured'. The difference between them is just into how many Confluence pages the template has been split. The 'flat' version consists of one page per level 1 chapter (12 pages overall). The 'structured' versions consists of one page per level 2 chapter.

We've already prepared space exports for you:

But you also can export the space yourself - we gave the anonymous user the needed permissions.

How you can import them into your own confluence is described in the Confluence documentation: Import a Confluence Space

Pros:

  • easy to do, one space per project

Cons:

  • you need administrator rights to import a space
  • heavily depends on your Confluence version


Info
titlePro-Tip :-)

You want to make your document public available? There is still lots of free space in this confluence - just contact us!

2) Use one of the Confluence Plugins

There are two Confluence plugins available on the Atlassian marketplace which help you to create arc42-style docs in Confluence:

Just give them a try

Pros:

  • various, depending on plugin

Cons:

  • you need to be able to install plugins (not available for cloud instances)

3) Use docToolchain to import the AsciiDoc version yourself

docToolchain is an open source Gradle build which takes an Asciidoc document as input and renders it in various formats. I already works quite well but still lacks some documentation:

  1. download the Gradle build from github: https://github.com/rdmueller/docToolchain/archive/master.zip
    it already comes with arc42 "preinstalled" and the gradle-wrapper. So the only requirement is a working java installation
  2. convert the Asciidoc arc42-template to html:
    ./gradlew
    this creates the html version of the template within the build-folder
  3. configure your confluence access:
    open ./scripts/ConfluenceConfig.groovy and edit this config according to your needs and setup.
  4. publish the arc42-template via the Confluence REST-API directly to your Confluence space
    ./gradlew publishToConfluence
  5. start to write your documentation with Confluence as master

If you want to stay updated about the progress of docToolchain, just follow the twitter account @docToolchain. If you need help, please use the github issue-tracker.

Pros:

  • you can have several copies of the template in one Confluence by prefixing the pages with (for example) a project key
  • you don't need to have the admin role

Cons:

  • very technical

4) Use docToolchain to only publish to Confluence

With docToolchain lets you not only immport the template to Confluence, but it also allows you to use AsciiDoc as your master document. Just follow the steps above and start to write your documentation within the ./src/docs folder of the Gradle build. Everytime you want to publish your document to Confluence, run the standard Gradle build followed by ./gradlew publishToConfluence - only changes will be published.

Pros:

  • Docs-as-Code approach: use the same mechanisms for your documents as you use for your code
  • use PlantUML for diagrams withouth having to install the Confluence plugin
  • use all features of AsciiDoc together with the benefits of Confluence (watchers, comments etc.)

Cons:

  • even more technical
  • does not come with an easy to use editor


Info
titleThanx!

PS: a big "Thank you!" to Atlassian for providing this cloud instance of Confluence!