HackerTube

Consistent Technical Documents Using Emacs and Org Mode

spudlyo2 HN recommenders · 2020–2025
74K views · demo · evergreen · Uploaded 2019-11-17

A demo of writing technical documents in Emacs Org mode using org-babel, so that code blocks and generated content stay consistent when things change. The author shares the demo files and his dotfiles.

HN commenters recommend it as a practical illustration of what Org mode and literate programming can do for documentation.

Testing, debugging & developer toolsSoftware practice, open source & careers

Watch on YouTube

5 comments from Hacker News

@rwnspace2020 · in “Ask HN: Resources to grok Emacs and use it well?”

This is what I've done the past couple weeks and it's going pretty well: Start with plain Emacs. Print/write out the popular cheatsheets. Just make sure you know how to exit, access the documentation, and move around the windows/frames/buffers. Get Melpa & install some packages. Play with the config, adding keybindings, figure out hooks and so on. Copy some elisp functions from dotfiles on Github. Spam the documentation command on everything. Get frustrated with how much tinkering you need to do to get the crazy setups you've seen on blogposts. Stay motivated by consuming more content about custom setups. Discover the magic of magit and parinfer and dired. Look up some of the org-mode/PIM heroes on github, usernames: novoid, alphapapa, karlicoss Install Doom. Tinker with it a bit. Take notes of your learning in an org file. Tinker some more. Go back to plain emacs for a bit. Then try spacemacs. Go straight back to Doom because it's faster and you now understand enough about emacs to be scared of spacemacs' layers. Below are some links to help you along the way. [LINK] [LINK] [LINK] [LINK] [LINK] [VIDEO] [LINK]

CitesView on HN
@d0mine2020 · in “Text-Only Websites”

Org mode supports inline Latex that can be exported to html. Here's a nice demo on how to write tech docs using Emacs and Org mode [VIDEO]

RecommendsView on HN
@spudlyo2021 · in “From Vim to Emacs in fourteen days (2015)”

I made a video[0] showing off the power of org-babel, which is the part of org that lets you embed dynamic code blocks in your document. In the video I write a little essay[1] on how git stores data that has a lot of dynamic content that is managed by org. It's a bit like reproducible research or literate programming, but for me it's all about writing technical documents that are easy to keep consistent when things change. [0]: [VIDEO] [1]: [LINK]

RecommendsView on HN
@spudlyo2021 · in “The open calendar, task and note space is a mess”

Org mode does a lot of different things, but one use case I find interesting is to be able to mix prose and program output in a technical document in a way that keeps things consistent when things change. I made a video[0] a year or so ago that explores Org's literate programming features that I think does a pretty good job of illustrating the power of Org. [0]: [VIDEO]

RecommendsView on HN
@spudlyo2025 · in “Atuin Desktop: Runbooks That Run”

Thanks for the shout-out! I think org-babel is really well suited for this task, and can make some really great documentation. You can check out the video[0] from the talk and a git repo[1] with a more advanced demonstration. [0]: [VIDEO] [1]: [LINK]

RecommendsView on HN