Revision-Secure Creation of Solution Architecture Documents (S-AD)

In today’s highly digitalized world, documentation in enterprise architecture (EA) is indispensable. It ensures that complex architectures are understandable and traceable while meeting legal and internal requirements for compliance. Particularly in regulated industries such as finance, healthcare, or the public sector, adherence to these requirements in documentation is crucial.

A solution that has proven to be both efficient and revision-secure in practice is the use of Asciidoc in combination with GitHub. This approach allows for clear, structured, version-controlled, and collaborative creation of enterprise architecture documents like Solution Architecture Documents (S-AD). Adding Confluence as a repository for generated PDFs enhances the ability to store, organize, and access important documentation in a central platform that is widely used in enterprise environments.

In this article, I will show how to use this method to create revision-compliant documentation and store generated PDF versions in Confluence.

What is Asciidoc?

Asciidoc is a lightweight markup language that makes it easy to create structured documents. Unlike XML or LaTeX, Asciidoc is easier for developers and architects to learn because of its simple syntax, and the resulting text is clean and readable. It can be used for both simple documentation and complex technical manuals or architecture documents.

Benefits of Asciidoc for Enterprise Architecture:

• Readability: Since Asciidoc is human-readable, architects and developers can start creating documents without needing special tools or training.

• Flexible output formats: Documents can be exported to various formats, including PDF, HTML, EPUB, and more.

• Modularity: Asciidoc supports the inclusion of external documents or snippets, which enhances documentation modularity.

• Easy to learn: As a text-based language, it is particularly well-suited for version control in Git.

GitHub for Revision-Secure Versioning

GitHub is the world’s leading platform for version control and collaborative software development. It allows teams to work on shared projects while ensuring that all changes are traceable. By using Git as a version control system, all changes to documentation can be tracked in full detail.

Benefits of GitHub:

• Version control: Every time a change is made to a document, a new version is created and logged, ensuring complete traceability.

• Collaborative workflow: Multiple people can work on the same document, propose changes, and discuss them via pull requests.

• Branching and merging: Different versions or variants of a document can be created in separate branches and merged later.

• Revision security: Changes are immutably recorded and can be restored at any time.

Storing PDF Documents in Confluence

Confluence, a popular collaboration and documentation tool used in many enterprises, is a great choice for storing and managing final PDF versions of architecture documents. While GitHub is optimal for managing and versioning the source files (written in Asciidoc), Confluence serves as a central hub where non-technical stakeholders can easily access, review, and approve the documentation without requiring knowledge of GitHub.

Benefits of Using Confluence for PDF Storage:

• Centralized access: All finalized documents, such as Solution Architecture Documents (S-AD), are stored in a central location accessible to relevant stakeholders.

• User-friendly interface: Confluence is widely adopted in enterprises, making it an ideal platform for storing documents that need to be accessible to a variety of users, including non-technical teams.

• Version control: Confluence supports versioning, allowing you to upload updated versions of documents and keeping track of historical versions.

• Permissions management: Confluence allows fine-grained access controls, ensuring that sensitive documents are only accessible to authorized users.

Step-by-Step Guide to Using Asciidoc, GitHub, and Confluence for S-AD

1. Setting Up a GitHub Repository

First, create a new repository in GitHub that will serve as the central location for the architecture documentation source files written in Asciidoc.

• Create a repository: Set up a new repository on GitHub. Choose either a public or private repository based on your organization’s requirements.

• Add .gitignore: To exclude unnecessary files from version control, add a .gitignore file to filter out temporary files or logs.

2. Creating a Simple Structure with Asciidoc

Define the documentation structure. You can start with a simple directory structure that organizes your documentation into modules.

• Directory structure:

/docs
    ├── README.adoc
    ├── introduction.adoc
    ├── architecture-overview.adoc
    ├── components
           ├── component1.adoc
           ├── component2.adoc

• Creating content in Asciidoc: Each .adoc file represents a module or chapter of the Solution Architecture Document. For example, introduction.adoc contains an introduction to the architecture, while component1.adoc details a specific architecture component.

3. Revision-Secure Work with Git

To ensure revision security, all changes to the documentation content must be saved using commits.

• Committing changes:

git add .
git commit -m "Initial draft of architecture overview"

This ensures that all changes are logged. Each commit is assigned a unique ID, providing clear traceability.

• Branching strategy: It’s advisable to use a branching strategy to make changes in isolation. For example, features, bug fixes, or documentation updates can be developed in separate branches and merged later.

4. Review and Approval Process

GitHub provides built-in tools for reviewing and approving changes. This ensures that every change to the architecture documentation is reviewed and approved by another person or team member.

• Pull requests: Each change should be integrated into the main branch via a pull request (PR). This allows team members to review the change and provide feedback if necessary.

• Code reviews: Through the review process, errors or unclear descriptions can be identified and corrected before approval.

5. Automated Document Generation

To automate the conversion of documentation into PDF or HTML formats, Continuous Integration (CI) tools like GitHub Actions or Jenkins can be used. This generates a new version of the documentation automatically with each change.

Example of a GitHub Action to convert Asciidoc to PDF:

yaml

name: Build Asciidoc

on: [push]

jobs:
  build:
  runs-on: ubuntu-latest
  steps:
     - uses: actions/checkout@v2
     - name: Install Asciidoctor
     run: sudo apt-get install asciidoctor
     - name: Convert Asciidoc to PDF
     run: asciidoctor-pdf -r asciidoctor-diagram docs/*.adoc
     - name: Upload PDF
     uses: actions/upload-artifact@v2
     with:
       name: documentation
       path: docs/*.pdf

6. Uploading PDFs to Confluence

Once the PDFs are generated, the next step is to upload them to Confluence to make them available for wider organizational access. This can be done manually or through an automated process.

Manual Upload:

1. Log in to Confluence and navigate to the appropriate space or page where you want to upload the document.

2. Edit the page and click the attachment button to upload the PDF file.

3. Insert the PDF link or embed the PDF directly on the page using Confluence’s document viewer macro. This allows users to view or download the document directly from the Confluence page.

4. Optionally, add versioning information to the Confluence page or create a dedicated section for archived versions.

Automated Upload:

For automation, you can leverage tools like the Confluence REST API. By integrating the REST API with your GitHub Actions or Jenkins pipeline, the latest PDFs can be automatically uploaded to Confluence with each new release.

Example of using the Confluence REST API for automated upload:

curl -u 'username:password' -X POST -F 'file=@docs/output.pdf' \ "https://your-confluence-url/rest/api/content/page-id/child/attachments"

This can be integrated into the CI/CD pipeline, allowing seamless uploads of updated PDFs every time a new version is generated.

7. Ensuring Revision Security

Ensuring revision security means that each version of the architecture documentation must be archived immutably. In addition to GitHub's built-in version control, Confluence provides its own versioning features.

• Versioning in Confluence: Confluence tracks each version of an uploaded file, so any previous version of the PDF can be restored or viewed if needed.

• Tagging in Git: Use Git tags to label specific releases of your documentation:

git tag -a v1.0 -m "Release of version 1.0"
git push origin v1.0

Conclusion

The combination of Asciidoc, GitHub, and Confluence offers a powerful and flexible solution for creating revision-secure Solution Architecture Documents in enterprise architecture. While Asciidoc provides the flexibility and modularity needed for efficient documentation creation, GitHub ensures version control and collaborative editing. By using Confluence for PDF storage, organizations gain a centralized and user-friendly platform to access, manage, and archive final documents.

This workflow ensures that all stakeholders, technical and non-technical, can engage with the architecture documentation in a controlled and revision-secure manner, while leveraging the advantages of modern version control and documentation platforms.