Cobwwweb logo

Three Ways to Visualize File Structure in Documentation

Apr 13, 2020

I was writing some documentation for an Ample internal project a few weeks ago in which I wanted to show the way a project's files and directories were organized.

Many prefer to visualize this structure in a tree format. For example, here's the List view in Mac's Finder application:

As I wrote the doc, I considered the ways in which I have achieved this type of visualization in the past.

Method 1: Bullets

The very first way I learned to represent file structure was by using bullet points. Here's an example, pulling from the screenshot above:

I've also done something similar but made it look more official by putting it in a code block:

- package.json
- src/
  - images/
    - image-01.jpg
    - image-02.jpg
  - templates/
    - page.html
    - post.html
  - index.html

That's not too bad. It's good in a pinch because it's easy to move quickly. But it's not great to read — I get lost when nested a few levels deep.

Method 2: Screenshot

I've also taken the approach of simply sharing a screenshot, as I did above. Visually, it works well. It gets the point across and is really quick to throw together.

The problems with the screenshot approach are twofold:

  1. Anyone who wants to adjust the documentation in the future needs to take a new screenshot, which means they must also have the files on their computer.
  2. It's an image (not text), so readers can't copy the contents but would have to retype.

Method 3: Linux Tree

When I was writing this latest set of documentation, I really wanted it to shine. I wanted to look back on it and think, Gosh, that's the best stale doc that ever existed!

I'd seen fancier versions of tree structures around, so I decided to dig in. Ultimately, I decided to follow inspiration from Linux's tree command, and went with this approach:

├── src/
│   ├── images/
│   │   ├── image-01.jpg
│   │   └── image-02.jpg
│   ├── templates/
│   │   ├── page.html
│   │   └── post.html
│   └── index.html
├── package.json

The visualization above uses four key characters to represent structure:

These characters are considered box-drawing characters, and they go back a long time.

To build the structure, we combine the characters together. This makes it a little it easier to read. It works like this:

It takes quite a bit longer to type this in this format manually, but the result is easy to read and worth the effort (if there aren't too many files). It also takes less effort to co-write and to maintain over time because it's just text.

And — BONUS! — if you have the files stored locally, you could actually use the tree command. (On mac, it's available through Homebrew.) Then you get the best of both worlds — it's fast to create, but easier to maintain compared to a screenshot.

Any one of these methods will work fine. After learning about the Linux tree approach, that's become my preference, especially if I have the files stored locally. I will really only use the screenshot approach if I want my doc to have some visual stimulus and if readers are unlikely to copy the text. And still, in a pinch or a less formal setting, bullets can still do the trick for me.

Did you learn something or find this article interesting?

If so, why not

Want to receive exactly one email every month with new articles, tools, and references I've discovered? Sign up below. (More info here.)