Sometimes a directory structure needs a little extra information. Even the most well thought-out directory names lack the expressiveness of a few short remarks. My solution for these cases has been to add a file named __dir_info__.txt to a directory requiring additional details. This file provides an explanation of the directory's purpose, which typically starts with This directory contains ..., and is formatted using AsciiDoc.
Let's look at an example:
= foobar
:date: 5 January 2015
This directory contains files related to foo-ing and bar-ing.
The title is always the current name of the directory, in this case foobar. The date is when the file was created or last modified. An author tag or other metadata can be added if desired. The body should be concise, no more than a few sentences. If a file naming convention is used in the directory, be sure to provide the details.
There are other options for documenting directories such as using the project readme file or the traditional FILES file. However, the explicitness of __dir_info__.txt is a great advantage.
