100% this. And yes, good documentation takes a lot of investment but it pays off like compound interest. But with that done, it becomes even more important not to pull the carpet for no good reason, you are building a tower and documentation is at the foundation.
We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then jump to the docs. This investment keeps on paying of as we use Lowdefy to build customer apps, new devs in the team typically take less than two week to get up to speed and start making contributions, the sharp ones, just a two or three days.
This year, we’re extended our documentation onto customer apps aswell, with flow diagrams, state machine definitions, detailed field level explication schema definitions, and end user test procedures. The key here for this documentation is detail. It should be easier to reach for the docs and the the answer, than to dive in the code and interpret it.
It is important to add to this a culture of actually reading the docs. Kudos here to my co-founder Sam. First developer I’ve ever met that reads ALL the docs before touching a line of code. When we say let’s pick up some tech, he dives in and reads every page of doc he finds. The effect saves time and results in much much better technical decisions. You don’t get stuck in the unknown, you immediately know where to go look if you are unsure, and architect a better big picture.
This, given of course that the tech you are picking up has good docs.
I wish reading docs more or less fully was more normalised. Time and again I find myself suddenly the, or close to the subject matter expert just because I actually read the documentation of what everyone else had already been working with for years, but was new to me. I don’t consider knowing a technology or tool without that step.
As you said, without it, you’re in the dark, doing guesswork. Doing that with multiple people, like a call with everyone guessing, is even worse. Just have everyone read the docs on their own time. So valuable.
Whats the point in reading thousands of pages of documenation for an ephemeral and constantly changing project? In order to justify deep dives, the software itself has to be stable enough. I plan to read the entirety of the ANSI C specification for instance; it is a justified endeavour because ansi C is a stable standard with compilers implementing it for a long while. For a constantly changing project of course documenation is still important but it should be more geared toward quickly cluing you in on the specific part you are interested in, and hopefully make diffs easily presented and available.
We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then jump to the docs. This investment keeps on paying of as we use Lowdefy to build customer apps, new devs in the team typically take less than two week to get up to speed and start making contributions, the sharp ones, just a two or three days.
This year, we’re extended our documentation onto customer apps aswell, with flow diagrams, state machine definitions, detailed field level explication schema definitions, and end user test procedures. The key here for this documentation is detail. It should be easier to reach for the docs and the the answer, than to dive in the code and interpret it.
1 - https://github.com/lowdefy/lowdefy