Doc blocks are mandatory, imho, but also a separate topic. The problem is that a lot of developers use the existence of docblocks and code comments as an excuse to not have to do non-code documentation.
I argue, in the post, that non-code documentation is also important, because it fills a different role than in-code documentation. Ideally you would have both!
I'm quite undecided. On most projects that had architecture docs, I was the person to write them. I never referred to them again, nor did anybody else.
I can see them being helpful should I disappear from a project, but I'm not convinced they are essential. They also take time, which is time not spent doing something else.
That's fair, I'd say it depends somewhat on the project. But also, fixing the knowledge silo is, long term, a thing worth doing for the project. That's an extra point I could add to the subject, thanks for that :)
Doc blocks are mandatory, imho, but also a separate topic. The problem is that a lot of developers use the existence of docblocks and code comments as an excuse to not have to do non-code documentation.
I argue, in the post, that non-code documentation is also important, because it fills a different role than in-code documentation. Ideally you would have both!
I'm quite undecided. On most projects that had architecture docs, I was the person to write them. I never referred to them again, nor did anybody else.
I can see them being helpful should I disappear from a project, but I'm not convinced they are essential. They also take time, which is time not spent doing something else.
That's fair, I'd say it depends somewhat on the project. But also, fixing the knowledge silo is, long term, a thing worth doing for the project. That's an extra point I could add to the subject, thanks for that :)
Found the problem! Hehe ;)