Richard Bucker

Documentation in Code or Code in Documentation; that is the question

Posted at — Apr 8, 2015

Given that Go now includes go generate I’m wondering if I should use markdown syntax to define and document my code or code my documentation.  For example I have a struct with about 100 fields and at some point I need to develop some real enduser documentation in the form of something that looks like a transaction and this is usually best viewed as a table.

  • field name
  • starting pos
  • length
  • data type
  • validation or regex
  • description
and so on.  Using MarkDown means that I can generate proper enduser (non-programmer) documentation. Using go’s generate function I should be able to convert the MarkDown back to code and I can also generate proper PDF and HTML for the enduser.

I might even be able to embed code, in formatted, function form so that it could be exported and then compiled.