kramano / docToolchain

see http://rdmueller.github.io for more details

docToolchain

create awesome docs!

docToolchain is an implementation of the docs-as-code approach for software architecture. The basis of docToolchain is the philosophy that software documentation should be treated in the same way as code together with the arc42 template for software architecture.

How it all began…​

docs-as-code

Before this project started, I wasn’t aware of the term docs-as-code. I just grew tired of keeping all my architecture diagrams up to date by copiing them from my UML tool over to my word processor.

As a lazy developer, I told myself 'there has to be a better way of doing this'. And I started to automate the diagram export and switch from a full fledged word processor over to a markup renderer. This enable me to reference the diagrams from within my text and update them just before I render the document.

arc42

Since my goal was to document software architectures, I was already using arc42 - a template for software architecture. At this time, it used the MS Word template.

But what is arc42?

Dr. Gernot Starke and Peter Hruschka created this template in a joint effort to create a standard for software architecture documents. The dumped all their experience about software architectures into not only a structure but also explaining texts. These explanations are part of every chapter of the template and give you guidance on how to write each chapter of the document.

arc42 is available in many formats like MS Word, textile and Confluence and all these formats are automatically generated from one golden master which is formatted in asciidoc.

docToolchain

In order to follow the docs-as-code approach, you need a build script which automates steps like exporting diagrams and rendering the used markdown (asciidoc in case of docToolchain) to the target format.

Unfortunately, such a build script is not easy to create in the first place ('how do I create .docx?', 'why does lib x not work with lib y?') and it is also not too easy to maintain.

docToolchain is the result of my journey through the docs-as-code land. The goal is to have an easy to use build script which only has to be configured and not modified and which is maintained by a community as open source software.

The technical steps of my journey are written down in my blog: https://rdmueller.github.io.

This readme is intended to be

The Manual

Let’s start with what you’ll get when you use docToolchain…​

Benefits of the docs-as-code Approach

You want to write technical docs for your software project. So it is very likely that you already have the tools and proccesses to work with source code in place. Why not also use it for your docs?

Document Management System

By using a version control system like Git, you get a perfect document management system for free. It let’s you version your docs, branch them and gives you an audit trail. You are even able to check who wrote which part of the docs. Isn’t that great?

Since your docs are now just plain text, it is also easy to do a diff and see exactly what has changed.

And when you store your docs in the same repository as your code, you always have both in sync!

Collaboration and Review Process

Git as a distributed version control system let’s you even collaborate on your docs. People can fork the docs and send you pull requests for the changes they made. By reviewing the pull request, you have a perfect review process out of the box - by accepting the pull request, you show that you’ve reviewed and accepted the changes. Most git frontends like Bitbucket, Gitlab and of course Github also allow you to reject pull requests with comments.

Image References and Code Snippets

Instead of pasting images to a binary document format, you now can reference images. This will ensure that those images are always up to date every time you rebuild your documents.

In addition, you can reference code snippets directly from your source code. This way, these snippets are also always up to date!

Compound and Stakeholder-Tailored Docs

Since you can not only reference images and code snippets but also sub-documents, you can split your docs into several sub-documents and a master which brings all those docs together. But you are not restricted to one master - you can create master docs for several different stakeholder which only contain the chapters needed for them.

many more Features…​

If you can dream it, you can script it.

• Want to include a list of open issues from Jira? ✓ Check.

• Want to include a changelog from Git? ✓ Check.

• Want to use inline, text based diagrams? ✓ Check.

• and many more…​

Let’s get started

Assuming that you first create your solution architecture and then the code, you simply start by getting a copy of the current docToolchain repository. The easiest way is to clone the repository without history and remove the .git folder:

linux with git clone

git clone https://github.com/rdmueller/docToolchain.git <your project name>
rm -rdI .git

Another way is to download the zipped git repository and rename it:

linux with download as zip

wget https://github.com/rdmueller/docToolchain/archive/master.zip
unzip master.zip
mv docToolchain-master <your project name>

If you work (like me) on a windows environment, just download and unzip the repository.

This should already be enough to start a first build:

linux with gradle wrapper

./gradlew

linux with maven wrapper

./mvnw

windows with gradle wrapper

./gradlew

windows with maven wrapper

./mvnw.bat

As a result, you will see the progress of your build together with some warnings which you can just ignore for the moment.

The first build generated some file within the <project>/build folder:

<project>:
    build:
        docs:
            html5:
                images:
                arc42-template-de.html
                arc42-template-end.html
            pdf:
                arc42-template-de.pdf

Congratulations! if you see the same folder structure, you just managed to reander tha standard arc42 template as html and pdf!

If you didn’t get the right output, please raise an issue on github