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:

• Code
• Config
• Wiki
• Issues
• Dependencies.

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.

Playtime

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:

• [ ] Todo Task1
• [x] Done Task 2

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).