Software architecture document

This use case describes how to make use of Git for Confluence in a typical software development artifact such as a Software Architecture Document.

A software architecture document is a bird's eye overview of the software you build. It is used to communicate, at a glance, how the software is structured. It helps understand the software’s modules and components and point out important design elements like protocols or interfaces. It’s a tool to communicate with others—developers and non-developers—about the software.

Source code

You may want to communicate protocols or interfaces that a developer needs to implement when extending the software. This is most easiest illustrated with some source code. Source code that you already have in Git! You can easily share that code in the confidence that it will always be up to date.

Architectural design records

More and more projects colocate their architectural decisions in Architectural design records (ADR's) next to the source code in Git. This works great for developers, but sometimes you need to share (part) of that information in another, possibly more formal form, such as an SAD. This is where the markdown support in Git for Confluence comes in handy. Markdown files can be shared in Confluence and will be rendered to look just as great as any other content in Confluence. And best of all, when you make updates to that markdown files and push a newer version to Git, your Confluence page will be up to date and show that version!

Diagrams

SAD's typically contain UML diagrams of all sorts to help understand layering, components and more. Chances are you create these diagrams in PlantUML format and you probably already have them in a Git repository where you keep them up to date. Git for Confluence can render PlantUML source files right from Git and show rendered images as part of your documentation.