by

Sneak Peak: The Open Design Doc

Aug
04
'
17

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...

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...

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:

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!

Discussion on /r/Citybound
Support Citybound