Recent searches
Search options
One of the hardest things to do is to keep a complete conceptual model of the software you’re building in your mind at all times (if you hear people talking about “getting into the flow”, a lot of that is about constructing or reconstructing that model in your mind before you’re able to be productive in making changes to an existing piece of software).
There are lots of things we can do to make this easier.
Modularisation is one of those things (so we don’t necessarily have to keep everything in our heads at the same time).
A test harness is another (so that when we invariably fail to keep everything in our heads and make a change over here that breaks something else over there, we are alerted to it as quickly as possible).
But documentation also plays an important part – especially when you’re bringing someone new onto the team or bringing yourself back to the team after a week or two away. And documentation that helps you build a conceptual model of the software in your head is usually one of those things that’s lacking.
So, to try and address this in Kitten, I’ve started to write – in addition to the (currently, woefully inadequate) reference guide¹ and tutorials² – a technical manual:
https://kitten.small-web.org/reference/technical-manual/
Think of its as the equivalent of those old-school factory service manuals you would get for cars and even computers, back in the day.
Eventually, you should be able to read the technical manual to form a conceptual model of how Kitten works. Hope you find it useful.
¹ https://kitten.small-web.org/reference/
² https://kitten.small-web.org/tutorials/
100% this.
I've always wondered why it is so rare to find an open project website with a diagram or picture showing the software architecture and the main ways information flows through it - or just how it works.
It would help new developers to get to 70% of the required understanding before they start making their own changes.
Some floss is so big it definitely needs pictures imho. Gimp. Linux kernel. Even its networking or graphics stack. Libreoffice...
Unfortunately, creation and maintenance of good documentation is a full-time undertaking of its own. It requires a skill set at the level of, but certainly not the same as, the ability to design and create the code being documented. This results in a trap, because inaccurate documentation is worse than no documentation at all. So the developer has to devote time to keeping the documentation current whenever changes are made.
Even the Unity online doc is often out-of-date.
Sure, but a high level (no detail) architecture diagram showing 3 or 4 boxes would be incredibly helpful and won't go out of date easily - because (1) it's not high level if its content is rapidly changing, and (2) it doesn't need detail.
I'm just saying a simple picture has long lasting high bang for buck.
I think that makes a lot of sense. A simple, lasting diagram can be a great starting point to understanding even a complex system. I was kind of baffled about the relationship of JavaScript to a web browser's Document Object Model until I saw a diagram.
Probably, the key to success is knowing when to stop the documentation process, so the trap I've seen so many times doesn't ensnare your project.
I'm with Tariq (@rzeta0) when he says: "I've always wondered why it is so rare to find an open project website with a diagram or picture showing the software architecture and the main ways information flows through it - or just how it works" - that picture that speaks a thousand words is so often missing. 