Refactoring development

Ramblings from the trenches...

View on GitHub
12 August 2016

Software Archiology


                                                                                                  | | <strong>Markdown</strong>

Rust uses Markdown for it’s documentation. Github goes further by allowing references to pull requests, mentions and issues.


Software Archeology Rule 1: KISS

Ivan Moor’s post on software archeology has kept me thinking. Essentially they’re suggesting a long lived project needs to contain in its source control system:

With all of these key things in the same place, nothing will get lost. If they’re separate and upgraded / changed every 3-4 years to the next newfangled thing, then things get lost.


Grav is a markdown flat file CMS that could happily live in your source repository.

Next you need to ditch JIRA and represent your tasklist in markdown:

If you need to get fancier than that, you can have one page per issue, with your choice of metadata at the head of the page (in markdown ‘definition’ format).