One point that I disagree with is "Every question asked in an internal Slack is a policy failure. It means the existing information systems failed to deliver an answer, and the user falls back to manually asking the hive mind's tacit knowledge." I find it's usually a failure of the doc search mechanism. It's much faster to ask humans a vague question than try to form the right search query for the internal doc system, which is usually much much worse than Google.
This can be solved by making docs public, but also by having people respond with a link to the docs. So Slack can still be a good interface to Q&A, as long as a single answer is documented.
I agree. Everyone's notion of documentation, its placement and role, can be different.
Some workplace relies on self-documenting code, some would require technical specs to be written in an internal wiki, some uses function/class/module headers.
It is inevitable that someone would ask how should I read the documentation, and any question on slack should be treated as a chance for improvement and better UX for devs.
Repeated questions from different people is a sign of the lack of improvement in the same area.
My usual go-to method to partially solve this issue is to challenge newcomers to write the question they asked and the answer for it, including how to write it, or make change to an existing one, so that other newcomers will find it easier to onboard.
That wasn't my take. Good documentation doesn't equate bureaucracy.
20 years ago, Spolsky wrote a blog post about how good documentation need not be unreadably dry and soulless. [0] From which:
> Rule 1: Be Funny
> Yep, rule number one in tricking people into reading your spec is to make the experience enjoyable.
[...]
> if you work in a company where people will respect you less because your specs are breezy, funny, and enjoyable to read, then go find another company to work for, because life is just too damn short to spend your daylight hours in such a stern and miserable place.
I'm not sure I'd go quite that far - it seems a bit much to leave an otherwise agreeable position just because they insist on humourless documentation - but I think he makes some important points.
> You can write more or less tests, you can be more or less sure that something you just wrote is actually correct.
At the risk of taking things too literally: that's quite an exaggeration. Even the most cautiously written code (short of formal verification) often turns out have serious bugs.
Linus's law (curiously apparently written by ESR) famously states that given enough eyeballs, all bugs are shallow. This implies that the typical initial value of 2 eyeballs is inadequate, but even Linus's law doesn't seem to go far enough. Sneaky bugs can hide for years in mature codebases.
> If you take say SOLID which sounds kind of reasonable, the Single Responsibility Principle in an OCD way can only be met by unary functions. Everything else must be doing more than "one thing".
I don't see where this is coming from. Multiplication is an operation over two operands but it's clearly 'doing one thing', to the extent that this is even meaningful.
Hopefully the article is enjoyable to those that haven't read his blog, I stumbled upon it because I'm a fan on nintil in general, but I think it's interesting even if you aren't familiar with his other writings.
>Absent tooling to detect dead ode
I'm not sure if this is a pun that is over my head or a typo.
Thanks for the article. I think the most difficult issue to solve is the meetings one, especially now that so much work is being done remotely. It's easy to have inconclusive meetings in engineering because you can just handwave your way through a project that drags on for too long and any non-technical stakeholders will have no choice but to put up with it. Also, engineering is complex and it's easy to over-commit and end up with really tough problems to solve.
One thing I'd like to add is that a "meeting" should minimize the number of active participants. If a "meeting" has more than 4 people it should be considered a presentation. It's a waste of to be in a meeting and trying to follow a conversation that you aren't involved in. If there is information in that conversation that others need to hear, it should be documented in some way.
Thing is execution of Software Engineering is highly opinionated. People with diverse cultures have different needs & skills. It is very difficult to write one doc that doesn’t raise questions or meetings. I guess we can minimize them by holistically understanding the use of the doc we’re creating.
Ada makes a real effort toward if it compiles it works, which is an exaggeration of course but Ada is much closer to that ideal than is C. More recently we have Rust, but Ada is too often overlooked.
I'm not quite sure what to make of those criteria. If you want a platform for writing DSLs, I believe Racket Lisp is impressively flexible, but it's a somewhat exotic language.
For flexibility and conciseness, functional languages are the obvious place to look.
No, meetings are usually not for thinking. They are for delivering status to an authority figure while wasting everyone else's time for the convenience of said authority figure.
There are many misunderstandings in Software Engineering. The first main misunderstanding is that Software Engineering is about writing code. I would argue that is the main misunderstanding.
In reality, software engineering is about solving problems, business problems, process problems, machine problems, etc. using code in software as a tool.
The 80/20 rule applies here. 80% of time is spent analyzing and developing solutions, 20% of time is spent writing code and developing software.
Too many people focus on the code part, when they should be focusing on problem solving part.
This can be solved by making docs public, but also by having people respond with a link to the docs. So Slack can still be a good interface to Q&A, as long as a single answer is documented.