Why does writing matter in remote work?

Oof. Yeah, complaints about other people - if they are NOT formal - should not be in writing in the first place.

If you're making a formal complaint, by all means. But otherwise, treat it like you're posting it on the internet for everyone to see.

I think the trick is to write in a way that gets other people to read it, and in a way that's cognisant of the fact that that reading will be more akin to skimming. Gratuitous use of bullet points and bolding two or three key takeaways are the main quick hacks I use to in support of that goal.

Longer-form writing and proper prose are more useful for e.g. tutorials, but things like user stories or other reference material should really be written to be skimmable, in my opinion.

Some notes:

I'd generally try to disregard the fear that your docs won't be used. At worst, they'll allow people to determine the original design intent and reconstruct how and why the project diverged at some point after you stop working on it. As long as the docs are part of the version control scheme for the project, you should be fine. If you however are using "share drive version control" aka a bunch of copies of the documentation for each release on a network drive separate decoupled from the project, it might as well not exist. If that's the case, you need to get it in version control. Sorry that was a bit of a tangent but I had flashbacks to a previous project.

If you want people to read the documentation, make it concise. The ADRs can be verbose and logged as necessary. That's kinda the point of an ADR. They record the mindset and intent of the developer. Everything else however needs to be easy to jump into. Have a super concise summary that links to subtopics and put in the detail there.

If you want people to maintain the documentation, integrate it into the build system/CI. If you have code examples in your documentation, they need to be unit tested so that the build system will warn you when the docs are out of date. Another avenue is to associate documentation with source code so that merge checks require documentation associated with modified sections of code must be checked off before commit. Getting this right is definitely the hardest part with documentation but when done well, it is immediately evident.

Also I know I have seen articles like you mentioned but for the life of me I can't find them. If you come across them, I'd love if you could share some so that I can bookmark them.

One of the most useful habits ever.

> But I have a fear. What if nobody bothers to read it?

This is definitely a big problem, especially in cases when reporting up the chain of command or sideways (to colleagues or other teams).

People don't read.

A big part of the reason seems to be the low expectation of value from any text. Since most writing is not well organized and rambly, people just assume it's not worth reading. And to be honest, they would be right most of the time... except when they are not.

The problem is the well thought out email that summarizes all the info about the project from past meetings that took a day to prepare, contains all the important links to documents, and describes a well thought out strategy for next steps will get just as much attention as the average non-consequential email of the same length.

Sometimes I think we need to have color coding for the hours that went into writing a piece of text, e.g. a paragraph showing in dark font indicates many hours and synthesis went into producing it (including decisions, consultations, planning, feasibility, etc), vs. a light gray text that is just a random suggestion. Such a color coding might help signal to the non-reader crowd (most people) that something is worth reading... something like nutritional facts.