Sneak Peak: The Open Design Doc

Hey everyone! A couple days ago I saw the light on the other side of the tunnel of some code architecture work that was necessary for the economy - and it's already totally worth it! But I'm happy to be working on game code again. There is no significant progress to report on yet - I'm working on finding lots for buildings and putting families into (so far) random buildings.

The next ten days I will be on my first holiday since an eternity, but I couldn't resist to show you today the first glimpse of something that means a lot to me: The all new Open Design Doc. I'll give you the short version of why and what that is now and then announce it more elaborately when I had the chance to flesh it out some more.

Wouldn't it be nice if...

I had a place to write down all my detailed plans for Citybound? (Maybe I could even deallocate some memory space in my head!)

You had a place to find out about my plans, long before I get to implement them?

There was a very rough approximation of what part of the game is done how much?

Traditionally in the game industry (as far as I'm aware), there is one document describing for the whole team and all stakeholders what the game is going to be and how everything in it is going to work: the "Design Doc". Sounds exactly like what we need, but I wanted to go one step further:

Wouldn't it be super nice if...

we could not only capture my ideas, but also all of the many, super detailed, well thought-out ideas that you, the Citybound community, came up with?

we had a place where likeminded people could discuss these ideas and iterate on them together?

there was an official mechanism for me checking out your detailed ideas and reviewing them as proposals for extending/changing my Design Doc?

after this process, your ideas might end up in the official plan for the game?

...and the whole discussion and decision process, with all potentially necessary compromises/convincing etc. being publicly recorded?

we could similarly record my own changes of mind, for example based on how people actually interact with the game?

Well! Heavily inspired by how the Rust programming language handles proposals for design changes from people outside the core development team, I realized that I could just put the Design Doc on GitHub (where Citybound's code is already) and use the same toolset of forks & pull request to make all of the above possible!

The holy Design Doc, descending from heaven

‍

I decided to go ahead with that, and first came up with a general structure for the document.

Every page and sub-page, hierarchically covering all of the topics and parts of Citybound will have the following sections each:

Design Philosophy

Design Prior Art & Inspiration (Optional)

Design Decisions

Implementation Philosophy

Implementation Prior Art & Inspiration (Optional)

Implementation Decisions

Parts (which the topic consists of, with completion estimate and a link to the specific sub-page)

Gameplay Aspects (which this topic affects, with completion estimate and a link to the specific sub-page)

The pages themselves will actually live right next to the code files of Citybound, sharing the same hierarchical structure. In this way, the Design Doc additionally acts as an in-depth "motivational documentation" for the code, and after reading about the thoughts behind a topic, you could actually dive right into the code that maybe already implements some of the topic.

Happy with this structure, I started to put it into practise, but only managed to write drafts for two pages so far ("Citybound" - the top level page, and "Transport"), but if any of the above sounds exiting to you check out the branch of the Citybound repo, where the work-in-progress Design Doc already exists. I also started to extend the contribution guide with explanations about how to propose changes to the Design Doc.

Whenever I find time, I will write more of the pages of the design doc, until I feel that the majority of what's in my head is covered. Then I will do a bigger announcement inviting everyone to contribute ideas in this formal way.

Whoops, I only wanted to give a short glimpse but ended up with quite a detailed description... it really does mean a lot to me!

As always, let me know what you think! I'll read your responses but I can only truly reply once I'm back. Then we will also resume Patrons Calling!

Until then, all the best!