Uncategorized

Axolotl: a simple plain text documentation system

Plain text is in most cases an enough documentation approach to any activity: only some minimum conventions are required to create metadata and visual clues, both visually enhanced by the text editor.

I’ve been using for years a simple convention for creating plain text documents in which to store every technical activity, task or process in which I’ve worked along the day.

With just a few rules, quick and almost inexpensive documentation can be create, with these features:

  • quick and productive documentation of tasks
  • searchable by keywords
  • visual clues to documentation
  • a standard way for documentation interchange (common keywords, date and author conventions)

A development has been made for Sublime Text to visually highlight conventions and to use key bindings to simplify tasks. This can be ported to many other text editors. I’ve done it also for Editplus and Jota Text Editor.

You can find it at github here.

Here is an extract of an axolotl document, edited in this case with Sublime Text with my axolotl highlights:

axolotl_example_extract

Brief Description of axolotl documentation system


Date convention used is YYYYMMDD (ISO 8601 Calendar dates in basic format).

Files are stored with the date of the day as name in format YYYYMMDD.txt

These marks, keybindings and color highlighting are used with the help of the text editor:

  • names between double brackets represent metadata tags (highlighted as green colour):

                   [[circulosmeos]] [[20141127]] [[ntfs]] [[incident]]

The beginning of the metadata line is a heading specifying author (initials or alias) and date:

                   [[circulosmeos]] [[20141127]]

           Alt+2 keybind automatically creates this author+date heading. NOTE: if you use the code for Sublime Text, change your name in “circulosmeos Insert Preformatted Texts.py“, by replacing the text “place your name here!“.
Alt+6 inserts [[]] with the cursor between the brackets.
F5 inserts actual date in ISO 8601 basic format.

  • repeated characters are used as dividers between different parts of the document or to enclose certain blocks:
  • task divider: 79x ‘-‘ (cranberry color) (Alt+1)
    ——————————————————————————-
  • activity divider inside a task: 49x ‘.’ (yellow color: note that Sublime Text’s background is dark grey) (Alt+3)
    ………………………………………….
  • divider that opens and closes a literal block of text: 24x ‘+’ (yellow color) (Alt+4)
    ++++++++++++++++++++++++
    ++++++++++++++++++++++++
  • paths or hints are indicated between < and > in order to mark external or attached resources (yellow color) (Alt+8 (this left the cursor between the two chars))
    <screen capture of my error.png>, <https://github.com/circulosmeos/axolotl >
  • visually striking sets for some common tasks, which are repeated (these can be easily found using Sublime’s minimap):
    (((DOCUMENTATION_PENDING)))
    Alt+5 for one line of this.
    — PENDING —— PENDING —— PENDING —— PENDING —
    Alt+7 for one line of this latter one.

 

Usually, I create a document per day for common tasks, with name format YYYYMMDD.txt. But also separate files with tasks names can be created.

I do also cross-reference tasks in case it is needed, so for example a task tagged as [[20150304]] can contain references to docs on other dates (which will be easily found as the filename that contain them is that very same date in text format) in the form of for example:

See <20150124>, <20140730>. All using code developed at <20100421>.

 

Searching inside axolotl documents


Search by keywords is easy:

just select “find” (in Sublime Text, Ctrl+Shift+f will open a search under a specified path, where you can store all your axolotl .txt docs), and search by anything starting with “[[“: for example “[[firefox” and you’ll find all your tasks with that keyword (it is not needed to close the brackets unless you’re looking for  a specific keyword among others with the same beginning, which is usually quite odd). Sublime Text will show you a few lines extract from every file, so it is very fast to find what you’re looking for. Other text editors usually behave in a similar way.

Keywords can be other authors, in case you have their docs or you’re indicating their collaboration in your docs. Also references to some specific date can be searched by searching with “<20140730>”, for example.

Just remember to escape brackets in case you use regexps: “\[\[firefox”.

 

Convention for links between parts of the document


I use the following convention for links between parts of the document. For example, imagine you want to refer a another part or the document where you’ve documented how to use an advanced fdisk option: I would put there the text:

See <#fdisk advanced option>.

And in the part of the document where that is explained, I use the same “tag” text, prefixed by “:

:<#fdisk advanced option>

Use the expert fdisk option to …

 

Work accounting


Note that this documentation system provides the basis for a simple work accounting automation. In fact I use some scripts that can give me hints on what tasks has been more time consuming (usually task length can be a good indication of this: in axolotl it is measured as the distance between the first keywords line and the next long separator line), what tasks or processes are more repeated, etcetera.

In trimester/annual briefings this can give an idea of trends and account for “men/year” measures consumed by tasks in an organization.

Simpler… impossible.

 

Axolotl


btw, the axolotl (/ˈæksəlɒtəl/; etymol. Nāhuatl āxōlōtl /aːˈʃoːloːt͡ɬ/) is a neotenic salamander unusual among amphibians in that they reach adulthood without undergoing metamorphosis. Instead of developing lungs and taking to land, the adults remain aquatic and gilled.

It seemed to me a good metaphor to remember that sometimes the most simple and not evolved (plain text) solutions are just as functional as any other ones. In most cases, more functional, in fact.

Albinoaxolotl3

Axolotl biological description and photo extracted from wikipedia and wikimedia.

 

License


Axolotl description and code for text editors, distributed under GPL 3.

Advertisements

One thought on “Axolotl: a simple plain text documentation system

  1. Pingback: Axolotl statistics script… and gource animation! | circulos meos

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s