Text Based Notes | dbatoolz

If you worked with me even for a day you must have noticed I am constantly taking notes – that’s because I believe note taking is the foundation to problem solving. Here’s how it typically works – when I am called in to solve a problem on an existing project or to help architect a new solution I’ve noticed three repeating Problem Solving patterns I tend to use:

Prevention: if you avoid making a wrong decision in the first place it’s a way of solving a problem before it even occurs. And providing a solid example of what not to do is a great way to accomplish this.
Awareness: if you are aware of the weak links in the chain and the symptoms they typically exhibit you can orient and find the culprit quickly.
Profiling: if you profile the issue long enough, then overtime it becomes easier to identify the culprit by doing a pattern recognition exercise on the information you’ve gathered.

I can confidently say that all of the above techniques hugely benefit from careful note taking and note organization. And in this post I’ll explain how I manage my notes using a very simple method. Method that will help you organize notes and project files and help you find relevant information even years later by keeping the storage structure consisted from project to project.

Use Text Based Notes

I’ve tried popular apps like Evernote but eventually gave up on them because apps that store notes in non-plain text fail in one fundamental requirement I have – keeping my carefully crafted whitespace intact. Instead I use plain text with markdown syntax and can quickly convert any note to html or pdf format. Text notes can be read on any device, any OS and text is a timeless format that will be readable/searchable many years after you and I are gone.

Pick One Place to Store All Your Notes

It’s extremely frustrating when you can’t find the information you know you had. A solution I’ve adapted is to store all my notes in one top folder/directory organized by client/project. I even put my personal notes there under a client called PERSONAL – that way if I am searching for something I wrote down – I know to always look there first regardless of the work/personal context.

Create A Centralized Searchable Index for all Projects

This is key to finding things years later – I have a special folder called index and it contains a separate index file for each client/category combination that includes titles of every project under this particular client/category. For example if my client/category/project folder structure is:

clients
├── CLIENT1
│   ├── proj
│   │   ├── x_Category_I
│   │   │   ├── Project_A
│   │   │   ├── Project_B
│   │   │   └── Project_C
│   │   └── x_SUPPORT
│   │   │   ├── Ticket_1234
│   │   │   ├── Ticket_1235
│   │   │   └── Ticket_1236
├── CLIENT2
│   │   ├── x_Category_V
│   │   │   ├── Project_A
│   │   │   ├── Project_B
│   │   │   └── Project_C
│   │   └── x_SUPPORT
│   │   │   ├── Ticket_2234
│   │   │   ├── Ticket_2235
│   │   │   └── Ticket_2236

then the index files will be as follows:

index
├── CLIENT1x_x_Category_I.txt
├── CLIENT1x_x_SUPPORT.txt
├── CLIENT2x_x_Category_V.txt
└── CLIENT2x_x_SUPPORT.txt

and within each of the index files the contents will be as follows:

CLIENT1x_x_Category_I.txt
    20150205-14:14:32   CLIENT1/proj/x_Category_I/Project_A
    20150612-12:09:49   CLIENT1/proj/x_Category_I/Project_B
    20150706-22:27:29   CLIENT1/proj/x_Category_I/Project_C

CLIENT1x_x_SUPPORT.txt
    20150219-16:41:56   CLIENT1/proj/x_SUPPORT/Ticket_1234
    20150307-11:45:55   CLIENT1/proj/x_SUPPORT/Ticket_1235
    20150319-11:12:19   CLIENT1/proj/x_SUPPORT/Ticket_1236

CLIENT2x_x_Category_V.txt
    20150520-12:21:14   CLIENT1/proj/x_Category_V/Project_A
    20150528-15:54:25   CLIENT1/proj/x_Category_V/Project_B
    20150609-18:28:16   CLIENT1/proj/x_Category_V/Project_C

CLIENT2x_x_SUPPORT.txt
    20150619-10:34:37   CLIENT2/proj/x_SUPPORT/Ticket_2234
    20150624-13:36:46   CLIENT2/proj/x_SUPPORT/Ticket_2235
    20150626-21:33:41   CLIENT2/proj/x_SUPPORT/Ticket_2236

I then use nvALT to index the index folder and in turn it allows me to quickly answer the following questions:

what did we do for Ticket_2236? – answer in CLIENT2/proj/x_SUPPORT/Ticket_2236
what project did I start on 20150609? – answer in CLIENT1/proj/x_Category_V/Project_C

Note that every client is suffixed with an x and every category is prefixed with an x_ – this ensures that when you search for a client or a category name and it happens to be a part of a common word the search results are cleaner. For example what if the category name is DB – try searching for this in a repository full of database related topics – you’ll get everything, but when you change it to x_DB – results are only filtered for that category.

Obviously the index files are automatically maintained by the program I wrote (which I’ll share on my next post so stay tuned).

Rotate Long Term Project Notes on Daily Basis

We went over the client/category/project folder structure but what happens underneath that? It’s very simple – just plain text daily work notes that all share the name of the project and a timestamp of the day they were created on. For example under the folder CLIENT1/proj/x_Category_V/Project_C I might have:

-rw-r--r--@ 1 mve  staff  14126 Jun  9 21:04 Project_C_20150609.txt
-rw-r--r--@ 1 mve  staff  14689 Jul  7 13:04 Project_C_20150707.txt
-rw-r--r--@ 1 mve  staff   7314 Jul 10 17:33 Project_C_20150710.txt
-rw-r--r--@ 1 mve  staff  32269 Jul 10 17:25 Project_C_work.txt

Note the Project_C_work.txt – it’s a special local index file where all daily work files check-in and where I can add project level information such as client contacts, key dates/deliverables etc.. At this point you might be wondering why I rotate project notes on a daily basis instead of having one single text file per project? The answer is simple – having daily work files allows for:

better profiling – it’s easier to profile an issue when you can see how it progresses from day to day
better searching – I use BBEdit as my text editor and it allows me to open all files under a specific folder at once so if I switch to CLIENT1/proj/x_Category_V directory and type in bbedit Project_C – it’ll open all files under that project and keep them in the left pane of BBEdit editor allowing me to quickly switch from day to day and see what I worked on. Try to do this if everything is in one single file – not that easy
automated daily status reports for my clients – because I use markdown format in my text notes I can quickly grep (search) for ^# (headlines) in the daily work file and it’ll give me all the headlines for the day. I then paste these headlines in an email/status report and my client gets a 30k ft view of the work done today. I also attach the daily work file to my customer support portal which I maintain for each of my clients on hashjoin.com and by doing so provide an ongoing knowledge base to them.

Takeaways

Prevention, Awareness, Profiling are the three major methods used in problem solving.
Careful note taking greatly benefits the above methods and improves your problem solving capacity.
Adapting a repeatable Note Taking Workflow / Organization will ensure you can find relevant information quickly.
Storing notes in plain text will ensure long term compatibility and preserve whitespace.
Placing all notes (personal and business) in a single top folder ensures you’ll know where to find them later.
Indexing the notes by client/category/project/date simplifies search.
Rotating project level notes daily can help profiling, searching and status reporting on long term projects/issues.

If you liked this post – sign-up for my newsletter Confessions of an Oracle DBA.

Vitaliy Mogilevskiy July 13, 2015

Posted In: Operations

Tags: Evernote, markdown, Text