A set of resources to become a Practical Software Architect: decision making, efficient meetings, architecture guide, etc.
This repository contains a set of Software Architecture document templates and examples in Markdown format. It also includes scripts to generate a basic website in HTML (check result here). You can use it as a baseline to build all your Software Architecture docs.
These artifacts are described in the book The Practical Architecture Process, which main focus is not the Architecture Guide itself, but the process you follow to obtain these artifacts and a proper Software Architecture. Get the book on LeanPub.
There are six folders in which you can find multiple markdown files. Each file has some summarized information about what you should include there.
The main idea of the book is that you produce these artifacts based on a collaborative, lightweight, efficient process.
You shouldn't hide in a corner and write all this by yourself.
This repository also contains a script to generate a single HTML version of the Guide: generate-guide.sh
. You can use this script manually or include it as part of an automated process. A good practice is to use it from a pipeline to publish a new version of this guide every time you merge a work-in-progress documentation branch into master.
The scripts requires Pandoc to generate the Guide in HTML.
Your guide will be exported to the output
folder after running the script, in two different formats:
index.html
file. You can copy this file, pandoc.css
and the images
folder and you have your documentation website ready to be published.1_guide.html
file and others. You can use this approach if your sections get too big. The script also generates a file index_multipage.html
for your convenience.Once you generate the HTML version of the Software Architecture documentation, you can deploy it somewhere so people in your organization can access it.
As an example, I've included in this base set of files a .travis.yml
file that uses Travis integration with GitHub to deploy the resulting documents to a publicly-available S3 Bucket. Actually, you can have a look at the latest result right now: archguide.s3-website-us-east-1.amazonaws.com.
If you work with PlantUML and keep your .puml
files in this repo, you can use a command to automatically render all your files to PNG images: render-puml-images.sh
. Then you can include the images in your markdown documents.
You can either run this script manually or setup a pipeline that triggers it automatically when generating the output documents.
The script used in this repository requires Java to convert .puml
files to PNG images.
Please send me any feedback or question you may have by opening an Issue in this repository.