Directories

One of the difficulties I found over the years is finding a consistent format for my project, both writing and coding. I've written up a plot of how I organize my projects. There are a lot more details in that link, but I'll give a quick summary of them. You may consider reading the conventions page because it will explain some of the notation.

Many of these decisions are because I also use tools to process my files. If the files are in the same place, every time, then I don't have to write custom logic to handle those tools. I always know that markdowny-wc src/chapters/*.md works, no matter which project I'm in. It also means I can drop in a configuration file across all of my repositories and know it will work.

🛈 This really isn't the One True Way™, just the way I work. As it happens, it is based on my experiences of almost forty years of writing things. It also evolves slowly as things make more sense, but I've pretty much stuck with this system since about 2001.

Read Me

Most forges have support for showing the README.md file in any directory. The root level one, //README.md shows up on the front page as a general description of the project. I typically put high-level details in here:

  • The title of the project
  • The author since I have used bylines or format books for other folks
  • Copyright
  • ISBN numbers
  • The blurb/summary
  • The elevator pitch
  • Store links
  • The inspiration for the project

Over the years, I used to try putting README.md files in other places but they didn't really give any benefit besides spending time, so I stopped doing it.

License

Even when I don't intend to put a writing project in a public repository, I usually add a LICENSE.md file. Since most of my writing is Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International , I use the Markdown version of the license and put it there.

If the project isn't shared, an “All rights reserved.” should be sufficient.

Tasks

As I'm going through the project, occasionally I realize I need to do something but I don't want to lose my flow. To make sure I don't forget it (again), I throw everything into a //TASKS.md file. Usually this is just a bullet list but it is good since I can switch to that file, type, save, close, and get back without losing too much momentum.

My task files usually look this this:

---
title: Tasks
---

- Look for overuses of nodding
- Go through and check Brook's hair color

It isn't really fancy. Though, I keep wanting to make this a check list (in Markdown, this is a - [ ] Look for overuses of nodding) but that implies I want to keep the tasks I finished. In most cases, once I go back and finish it, I delete the line so an empty tasks file is a happy file.

Chapters

The main “source” of the project are the actual words. I treat all of them as chapters with short stories simply being single chapter novels. This means I have a consistent naming convention to identify the files which lets me use muscle memory or boilerplate processes to generate.

Creatively enough, I put these under the //src/chapters/ folder with each chapter being chapter-XXX.md with the XXX starting at 001 and incrementing one for each successive chapter. That means chapter eight is //src/chapters/chapter-008.md.

The reason I zero-padded the number is because the zero-padding ensures that the chapters are always alphabetical when I list files or view them in a file explorer. While chapter-5.md and chapter-10.md will sort correctly in some explorers, such as later Microsoft Windows file explorers, automated tools are rarely that intelligent and will provide it in lexical order which means chapter-10.md will come before chapter-5.md. The zero padding ensures that everything sorts it correctly.

The three digits is because I have written series that have had more than a hundred chapters. Having the consistent naming means my scripts don't have to be aware of one, two, or three-digit chapters which results is simpler and easier to maintain code.

I don't put the title in the file name because I found that it changes too often. However, others might find putting 001-enter-the-kitty-gunslinger.md would also work just as easily as a simple chapter-001.md.

Removed Chapters

Occasionally, I'll write a chapter and realize it doesn't make sense anymore. But I don't want them in the chapters folder, so I move them //src/removed/ folder and rename them to give a bit more context and change chapter to removed. For example, I might move chapter-004.md to removed-lily-wanders-her-stash.md.

The reason I do this is because I use “fuzzy find” a lot while I work. And I jump between chapters with Control-P 002 ENTER so I don't want any other “002” files because it slows me down. I want a full chapter number to find only a single file. But having the removed- at the beginning helps when I'm doing a more generic search, such as Control-P lily, and know which file is which.

Matter

An important part of the publication process is producing front and back matter. This includes things like fancy and bastard title pages, about the author appendixes, “see also”, and even simple things like dedications. They aren't really chapters per-se, but still important.

I group all of these into the //src/matter/ directory. Some example:

  • title.html is usually the title page and is usually straight-up HTML
  • bastard.html is the bastard version of the title
  • legal.md contains the legal information page including copyright
  • dedication.md is the book's dedication, if I have one
  • author.md is the “about the author” section

Title Pages

The title pages are HTML instead of Markdown. I use CSS to style them because usually they need some additional attention and are rather book-specific.

Data

I like to check information about characters, snippets of descriptions, or general notes as I go. These are usually a directory of free-free form files with cross-linking between them. The most common is one file per major character. For example:

  • //src/data/linsan.md contains information about Linsan, the main character of a novel

I might group these data files according to something that makes sense.

  • //src/data/shimusogo/gemenyo.md which gathers all the Shimusògo clan members in one place.

There are many reasons I do this.

The first is that most of these notes are snippets, removed phrases, or things about the character for that book. They don't really make sense to add to a wiki or more formalize the content. They are usually written with very little formatting but are useful for keeping consistent. I'll put things like eye colors, favorites form of dress, catch phrases, and even the first few times I describe the characters.

The second reason is that they are checked in. Which means they are control by source and if I make a change, I can see the previous version.

The third is they are part of the project. When I using something like Visual Studio Code, I edit the project root so I can use “Find in Files” to find all information, even ones in notes. A search and replace works across them so everything is kept up to date. It also means I can easily Control-P name-of-character ENTER to jump to that file without every taking my hands off the keyboard.

Finally, the fourth is that I have started to write various tools that use the data directory as a “lookup” of sorts. The intent is that it gives me a consistent location so I can Shift-F1 and see a little popup that gives a summary of the character. That isn't really ready for prime time, but it is cool to be able to click on a name and ask for a reminder of those character details.