I had started a new job in September, 2017. The first thing I did was to create a new private Git repository that only I had access to.

The first commit I made had a file named “20170916_InitialPlan.md” and it contained an email from my new boss that I copy-pasted into that markdown file. The entire contents was info helpful to me getting started at and acclimated to the new job.

The reason for this repository was to just keep some documentation in one easy place, and to not worry about OneNote or some other tool. As I went, I started formalizing the structure of this repository into a massive compendium of knowledge.

As a rule, I started making filenames in the format of “YYYYMMDD_description.md”. “20181007_blogpost.md” would be an appropriate filename for info about today’s blog post.

The reasons to create a new file were these:

• Had a meeting with discrete info to be captured as a unit.
• To save an interesting SQL query.
• To write down a business process or some software workflow.
• To make info searchable.

Searching for info is very good because I get an interesting property from my filename convention: the filenames in the search results instantly tells me the approximate date of the keyword. From that approximate date I can look at the other files in close date range and get the context.

A side point is that Elasticsearch does fantastically with Time Based Indices, in case you were thinking this sounds familiar to many logging frameworks.

The Topics

Eventually, I reached the point where having everything in one folder was unwieldy. I started categorizing the files into folders

- SQL
    - 20181007_QueryToFindDeadlocks.sql
- Oracle
- Java
- Azure
- Salesforce
etc.

This worked out pretty well. A few topics become so large, that I then broke it down even further by adding a new folder level for the month.

- SQL
    - 201810
        - 20181007_QueryToFindDeadlocks.sql
- Oracle
- Java
- Azure
- Salesforce
etc.

The Evolution

Sometime around the new year I was transferred to a different team and I decided to try a more formal daily file based around typical agile standup questions.

Each day I’d create a new file with the date named “Standup.md”

- Standup
    - 201810
        - 20181007_Standup.md

In this file, I put down these items

• What I am working on today.
• Anything I need to remember for later and I just wrote down quickly as a scratchpad.
• The current list of things I need to do, that don’t belong in a JIRA ticket.
• Information about any work-in-progress items that don’t need to be on the JIRA ticket for whatever reason. Yes, some of these do exist even though relevant information should be on JIRA ticket.

Each day when I create a new Standup.md file, I copy-paste the previous day’s contents into the new file, and then I trim down whatever is not relevant. The information on work-in-progress info will fall-off when that work is done, what I am working on yesterday may be the same thing I’m working on today, and odds are good the TODO list is probably not much smaller.

Other Files

The repository tends towards markdown and SQL files as the bulk of the content. I’ve also put general file blobs in there, such as a PDF of standard Oracle documentation that is just a useful reference.

Summary

This experiment in documenting my time at this job for over the past year has been extremely useful. Writing stuff down in a consolidate space and in a more formal structure has helped enormously. Do still write down stuff in JIRA or your company’s tracking software, but that tool doesn’t help at a personal level as much.