Adopting GitHub for documentation, and resulting blog changes
After having used Git(Hub) to work and collaborate on code for a long time, I have recently spent some time to merge and move various documentation artefacts to GitHub as well. This covers the Data Integration framework and Enterprise Data Warehouse (EDW) architecture documentation, most importantly the various Design Patterns and Solution Patterns. These patterns form the central body of content that actually try to explain how things work in practice.
I think it makes a lot of sense to use Github as a collaboration mechanism for documentation as well (i.e. not only for code). It’s just too time consuming to maintain various documentation sets in binary format (Word, PDF) as changes can’t be easily merged when you work across multiple teams and various geographical regions. Word has a great layout, but at the end of the day is a closed format that requires specific software to be used.
As a result, I have moved much of the documentation in the menu sections of this blog into a new documentation GitHub repository. Have a look at the collaboration section to get an idea of the scope of this, as well as an idea where to find it. The documentation on the blog pages in the menu, as well as many other artefacts in various other location have been merged.
As you can image, over time various small changes in some documents haven’t always been propagated to the others, and I found some of the earlier documents to be outdated. This is why I’m also in the process of re-reviewing and updating documentation where required.
GitHub is great for this, as it easily allows others to pick up some of the work and contribute as well. If people want to, they can even branch out specific parts of the content and take it into a different direction. True to the Git concept the solution with the most merit will ultimately survive because more people keep contributing to it. You can also use GitHub to keep track of issues and discussions around specific topics.
To really make this work the documentation will need to be in plain text (not Word) because this allows for diff views that highlight proposed changes – a sort of scalable change tracking. GitHub supports (it’s flavour of) MarkDown which is easy to use and doesn’t look too bad. You can also use (and/or embed) LaTex for this purpose if you use a lot of (math) formulas. From time to time you can choose to render ‘final’ versions as PDF, which doesn’t look that bad. With a bit of effort you can render this with corporate logos and things like that as well.
I’m aware of alternatives in this area, including things like Google Docs. But at the end of the day I’m a firm believer in the Git concept and see this as an effective way to continuously update documentation (across different teams and regions) and share this as well.
The DIRECT documentation (process control framework) has been moved to the DIRECT GitHub.
