Literate Documentation with Emacs and Org Mode | Hacker News Reader

Literate Documentation with Emacs and Org Mode

gitlab.com

93 pointsspudlyo10 comments

Literate programming is an interesting approach. I wonder if it is really helpful for building large systems though.

In my opinion, trying to understand a large codebase is a learning activity. True, documentation is important at times. However, it depends also on the author. If writing good code is hard, writing good literate programs is imho harder. Now one needs to be a good writer and a good coder. Probably the skills are transferable to an extent, but I think they are different things in the end.

Besides that, the ability to explore and try things out is also helpful for learning things. That's why I think Smalltalk is the most approachable language so far. You get a browser and a REPL (workspace), and the object explorer plus inspector tools. Not to mention the method finder. All these tools to let you learn how code works. I really miss having some of these tools in other languages, especially the browser. Even Lisp doesn't have that one afaik (correct me if I'm wrong).

In the end, I believe language facilities such as the ones I previously mentioned are more valuable to understanding than being able to wrap code in prose. Still, documentation is invaluable at times. So comments will (should) never go away.

There are notable exceptions. In scientific programming, code is tightly linked to scientific context and explaining stuff in prose is vital for being able to understand. Often, people claiming their code just reads itself just haven't worked on hard enough problems. Other than that, people seem to mistake the reason for having documentation: we aren't necessarily (just) explaining how something works, rather why you made a certain choice, why the alternative doesn't work etc.

Yes, writing a good literate program is more work, and it may not be for everything, but there are many cases where this approach can help communicating your work and save time in the process.

That being said, I'm not a huge fan of Org-mode, since it forces Emacs onto your collaborators. A much nicer method based on Markdown is Entangled: https://entangled.github.io/, though disclaimer: I'm the author of Entangled ;)

Literate programming shouldnt necessarily apply to application code for large systems but I almost always want more literate tests that clearly explain not just what should happen under all kinds of scenarios but why it does that. Even better if I had hyperlinked explanations for domain specific terms.

If I always had this I think I'd become fully productive on large systems 2x as quickly.

I dont think this need be achieved by hiring a unicorn coder who is also a great writer but by making tests more accessible and editable by good technical writers so that both parties can collaborate around behavioral tests that double as documentation.

I'd like to see literate programming melded with the docs as code approach. A simple way to see (say) myfile.go and myfile.md displayed side-by-side, with comments and their code targets aligned side-by-side during scrolling.

(Or, alternatively, comments & code interleaved... but then when the comments and code are both collapsible, it's not much different from current IDEs.)

This shouldn't be too awfully difficult. Process myfile.go to autogenerate myfile.md, which contains markers or tags or labels to indicate the points to align with the course code.

Is this making any sense ?

Yes it does. We (at the Netherlands eScience Center) will be building such an interface next January, extending Entangled (https://entangled.github.io). This approach uses Markdown and enables editing your code both in Markdown and generated source codes, synchronizing when files are written to. Currently with traditional documentation site generators like MkDocs, you can get nicely presented content, but what you suggest requires a bit more work. We will build better content navigation in Pandoc, and a side-by-side view as you suggest is definitely on the table. Also: outside contributions are more than welcome ;)

It does look nifty. Altho getting up to speed is non-trivial. I don't suppose you have any working examples in the Go language ?

Sadly nothing Go specific. We're working on making it easier to work with.

Go already has built-in support for tests and for executable examples (that go into generated package documentation), so it might get hairy.

You have to allow sudo without entering a password to use this document (to build Emacs)? I wonder if gksudo could not be used instead…

The issue with using gksudo is that it's a GTK application, and it drags in with it a ton of dependencies. The document (which does indeed build Emacs) needs to be able to run on server distros which do not have any GUI applications installed.

Reply on news.ycombinator.com