Wednesday, April 8, 2015

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

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.

No comments:

Post a Comment

prod, staging, QA, dev in your CI/CD?

I've been developing with CI/CD since before it was a straw, let alone a pipeline. No, graduates of 2020 you did not design or discover ...