Restructuring my Folders

10/25/2020

Journal

In my previous post on writing, I said I'd make a start on actually writing a novel... or story... or... whatever! And I have... sort of. I've created two projects and started doing research and adding notes and exploring the texts' voice. It's a long way from an actual start - still neither has a story - but it is something.

I've also added support to this website for displaying their contents, and will expand on that soon but... it's functional, for now; it works. It is good enough.

What I'm still trying to wrap my head around is... folder structure and actually keeping everything organised in a manner that makes sense.

In that previous post, I shared diagrams that look like this:

my-novel
├── README.md
├── docs
│   ├── characters
│   │   └── john-doe.md
│   └── locations
│       └── london.md
└── src
    ├── chapter-1.md
    ├── chapter-2.md
    └── chapter-3.md

That is the folder structure I'm using for my novels going forwards, and it works - it's a good system. I may change it around a bit in the future... Like, src/ is a good place to store the actual source files of the novel itself but... that might not just be chapters. What if it should also include images? Where should they go? src/ as well, I'm sure, but... just src/ or src/assets/ or what? Let's not worry about that now. It isn't an issue yet.

No, the issue I'm facing at the moment is... again, let's be honest, it's my own damn perfectionism - the enemy of doing.

See the structure of my content files on this website is as so:

content
├── blog
│   ├── blog-post-1.md
│   └── blog-post-2.md
├── projects
│   ├── project-1
│   └── project-2
├── prose
│   ├── book-1 **
│   └── book-2 **
└── screenplays **
    ├── series-1
    └── series-2

Where I've included a double-asterisk above, **, I'm indicating that these are Git repositories; they are included as Git submodules. I originally started out with every single one of my projects being a Git repository that I simply displayed the README document for... but... then I wanted to list ideas too that hadn't gotten to the stage of having a repository, so I abandoned it for those.

Screenplays too used to have individual repos, but I put all of them together in one big repo for... cleanliness... and I'm not really satisfied with that. They should be regarded as individual projects.

And of course 'projects' is poorly named. Those are in fact my programming work - both active projects and things at the idea and consideration stage.

Now... Adding all of my writing to GitHub to be fetched as submodules is creating clutter, but it's fine... GitHub doesn't need to be my nice clean interface to the world... my website should be. I can deal with GitHub presenting an unclear list of projects so long as I can sort them properly... here.

But I'm beginning to think...

Okay, here's what I'm thinking:

content
├── blog
│   ├── blog-post-1.md
│   └── blog-post-2.md
├── programming
│   ├── project-1.md
│   └── project-2.md
├── repos
│   ├── book-1 **
│   ├── book-2 **
│   ├── project-1 **
│   ├── project-2 **
│   ├── series-1 **
│   └── series-2 **
└── writing
    ├── prose
    │   ├── book-1.md
    │   └── book-2.md
    └── screenplays
        ├── series-1.md
        └── series-2.md

...or something like that.

repos/ becomes the defacto place where all outside submodules are stored. And with the right metadata stored alongside each project, I can easily search for them by kind: software, screenplay, novel, whatever...

programming/ is a clearer name for any coding project. Those aren't submodules in that directory, but the files ('project-1.md' and 'project-2.md') can list their associated repositories in their metadata... and I can choose how to display them. And this isn't a one-to-one relation. A single "project" could have multiple repositories, say a backend and a frontend.

writing/ then, similar sort of thing; these are files that describe where to find the repository contents for proper display. In the example above these are one-to-one! ...but they don't have to be. Say, I start a second season of a screenplay series, or add a sequel novel to an ongoing saga... I can choose to change how this gets displayed on my website for easy exploration.

This... This works for me. My repos are always easily found, since they're grouped together in one place - just like GitHub - and I can work the actual organising logic into the site code itself and by creating these... associations.

Yeah, that's nice. So... Todo:

  1. Reseparate thombruce/screenplays into multiple screenplay repositories.
  2. Move all content git submodules into a repos/ directory.
  3. Modify site queries to fetch these appropriately.

Oh, another thing - and it keeps slipping my mind... What about closed source?

Closed source projects is another part of the reason I migrated away from using repos for my programming projects in the first place, because it didn't make sense to fetch my closed source projects and expose them to the public when... that's... defying the point, really. Hence the move to project documents that simply describe the nature of those projects.

The same might become true of writing works. What if I ever don't want to publish a piece on my blog? What if it too should be closed source?

In such case, we simply do not include the repo but can include a document in the respective folder that says, "hey, I made this too, and you can find it here!!"

Just quickly, here's another alternative file structure...

content
├── blog
│   ├── blog-post-1.md
│   └── blog-post-2.md
└── projects
    ├── book-1 **
    ├── book-2 **
    ├── book-3
    │   ├── project.yml
    │   └── README.md
    ├── project-1 **
    ├── project-2
    │   ├── project.yml
    │   └── README.md
    ├── series-1 **
    ├── series-2 **
    ├── series-3
    │   ├── project.yml
    │   └── README.md
    └── series-4
        ├── project.yml
        └── README.md

We revert to use of a projects/ folder, but now it contains EVERYTHING! Asterisks still denote git submodules, but not everything in there is one now. Fore example book-3 is just a folder containing project.yml and README.md, and I would use project.yml to describe the nature of the project; its contents might be:

title: Book Three
type: novel

...external repositories would have this file too, making them easily searchable by kind or 'type' there.

It's got some benefits... but an immediate possible downside is... well, what if a project is split across multiple repos? What if they all need including?

That is a problem with this approach, for sure, but... well, I haven't hit that problem yet. And it's actually more easily avoided than I immediately thought. We simply, at that point, create a programming/ folder and do what... should amount to a minor set of changes to the website logic.

But, like, as a starting point... grouping together what... should all be considered "work", right? It makes sense. Right? (Hey, welcome to my struggle fighting against perfectionism!)

I think as a start, this last option is...

  1. Good enough.
  2. The easiest and quickest to put into place.
  3. Actually reinforces structural discipline by requiring repositories/files to identify their type in some way.
  4. It's actually the starting-point for the other approach - I can easily do this and migrate it to that.

...and I like that. Okay, that's how we're doing it.

Good enough!