New Approach of ILLiterate Programming via doc-code-merge: Stakes and Opportunities

 

‘’It's very common to embed code examples in technical documentation. However, doing so is kind of painful. First of all, the environment you use to edit the documentation may not be the same as the environment you use to write code. For instance, I generally use Dart Editor to write Dart code, but I use Sublime Text 2 to edit documentation written in HTML or Markdown. Secondly, it's difficult to run unit tests or use dart_analyzer if the code is trapped in documentation. This is a big problem for us on the Dart project because we move pretty quickly, and we want to make sure our documentation is always 100% correct. I've created a tool called doc-code-merge to solve this problem.’’ Has declared Shannon -jj Behrens.

The goal via this approach aims to let Developers write their documentation and their code examples completely separately.

In fact doc-code-merge aims to be the opposite of what Donald Knuth labelled Literate Programming. Therefore, when you run doc_code_merge.dart, it makes a copy of your documentation with all the examples merged in.

Using doc-code-merge aims to be also easy. Here how you can start to write some documentation:

 

According to the author, doc-code-merge automatically handles things like indenting code blocks when generating Markdown and HTML escaping code when generating HTML.

In addition, although doc-code-merge is written in Dart, it'll work with almost any programming language and with almost any type of documentation as long as the documentation is written in text such as HTML or Markdown. If you're interested in using doc-code-merge, you can check out the README.