How I Do Documentation and Learning with Asciidoctor

By: Daniel Hinojosa

Published on: May 16, 2026

Categories: Asciidoctor Study Learning Content

I have my own note-taking methods for learning and, inevitably, for creating material to make it easy. First off, I use Asciidoctor. Asciidoctor is far more powerful than Markdown, and you should be able to express far more with it. There are plugins that aid in editing. JetBrains editors, for example, have a feature that even allows you to copy and paste into the document.

Have a study directory for your interests

Create a directory for the item you wish to learn, for example, vim-study, git-study, kafka-study, cats-study, or claude-study. Have a consistent structure:

vim-study/
  README.adoc
  inbox/
  notes/
  projects/
  references/

Notes Directory

This is the content of what you are learning: concepts, explanations, comparisons, patterns, and your understanding and interpretation of things.

notes/
  buffers.adoc
  registers.adoc
  macros.adoc
  navigation.adoc

Projects Directory

This is your code. Projects can be broken into languages in case you are studying something that spans across different computer languages. It can also be broken up into concepts or sub-modules.

projects/
  vimrc-experiments/
  plugin-dev/
  macros-practice/

References Directory

Are you going to a conference? Listening to a speaker talk about a topic you are interested in? Add items like curated links, summaries of talks and books, and snippets of external material. I like to list out where I get them. I prefer these over link catalogs like Pinboard.

references/
  vim-help-summary.adoc
  videos.adoc
  articles.adoc

Inbox Directory

This is my brain dump, a dumping ground for ideas and maybe incomplete thoughts.

inbox/
  why-do-registers-work-this-way.adoc
  idea-vim-as-language.adoc

Consider a study directory

Consider placing all your study material in a single study directory. Choose to organize into subfolders if you need to.

study/
  vim-study/
  java-study/
  kafka-study/
  nix-study/
  typelevel-study/
    fs2-study/
    circe-study/
    http4s-study/
  scala-study/

Be ready to open these projects at a moment’s notice

These are your notes, and your learning lifeblood. If you learn something new, be ready to jump to the project to add a reference, a note, or a code sample. Need to look up something? Have a way to load these projects quickly.

Commit your notes to version control

Keep them safe, of course. Most of all, treat your study repositories like code quality. Ensure it is hygienic. Ensure that the repository is private.

Cross-Referencing

You can cross-reference by adding a section at the top that notes what this is related to and what prerequisites are needed to understand the note. This can provide what LogSeq and Obsidian offer, but with the advent of AI and agents, do you still need them?

== Related

* registers.adoc
* macros.adoc

Keep Notes Private, Make Knowledge Public

Notes are my sanctuary, my temple. I have notes, private thoughts, and even copyrighted material I can’t share, like e-books and conference slides. The information I gather from my note-taking will take different forms, such as giving presentations, creating write-ups, and delivering workshops.

Create Spin-Off-Projects separately

If you are creating a workshop or presentation, make those repositories public. Ensure you separate your private notes from your public projects that derive from them.