Add introductory material for acceptance test suite

1 files changed, 51 insertions, 0 deletions

diff --git a/yarns/010.yarn b/yarns/010.yarn
new file mode 100644
index 0000000..325232e
--- /dev/null
+++ b/yarns/010.yarn
@@ -0,0 +1,51 @@
+% jt: a tool for maintaining a personal journal
+% Lars Wirzenius
+
+Introduction
+============
+
+I maintain a personal journal using Ikiwiki. `jt` is a tool to make
+that easier by taking care of repetitive steps, such as creating new
+Markdown files for journal entries, etc.
+
+I mean `jt` to be a personal tool. It needs to work for me. If anyone
+else finds it useful, that is great, but I'm unlikely to want to spend
+much effort to make changes only for the benefit of others. That said,
+patches are welcome.
+
+This document is a description of `jt`, and also its executable
+acceptance test suite when given to the `yarn` tool (another of my
+personal projects).
+
+
+Overview
+========
+
+My journal is a bit more than a journal. It is a "personal knowledge
+base". But it's primarily a journal. There is a series of journal
+entries, called **notes**, ordered in a sequential time order based on
+the timestamp when the note was started. Notes can be tagged, using
+the Ikiwiki tagging feature, and they are linked to topics.
+
+* Notes are in a time series.
+* Some, but not all, notes are grouped into topics, by having a topic
+  page and pages related to the topic link to the topic page.
+* Topics in my journal tend to be specific projects, or specific books
+  I read.
+* Notes are tagged, using ad hoc tags.
+* Tags are mostly for indicating the type of a note: an idea, a rant,
+  meeting minutes, etc.
+
+Examples:
+
+* A note about an idea for a product I have may be tagged
+  "product-idea", but isn't linked to a topic.
+* If I'm buying a new dishwasher, that would be a research topic, so
+  it might have a topic page `research/2014/dishwasher`, and all notes
+  about this get linked to that topic page. They may also be tagged,
+  if that seems useful.
+
+With a structure like this, Ikiwiki renders a (static) web site from
+the journal source tree, and puts in all the HTML links between pages
+to make it easy to find what I need. When that fails, I use `git grep`
+in the source tree to find things.