[themodelplumber]

I've found it helpful to at least look at it as a personal preference, even if no one else wants it. If it helps you, do it.

Such best-practices are an interesting not-so-universal thing in a lot of areas. IMO this often has a lot to do with employer relationships.

I've found that a lot of people are really proprietary about documentation, (not even getting to architecture yet) and treat their time spent documenting as time spent giving away their negotiating leverage.

Sometimes this is a good point to consider though. The situation where you are happy with your work and the situation where the organization needs to start paying more attention to your value can be examined separately and you can make decisions about sharing your documentation work separate from decisions about the documenting itself.

Others don't feel a need to hold back, but they would rather work on more apparent or pressing issues (i.e. more obvious to them because of their differing work perspective). It is then left to the contingency thinker to justify themselves, which can be really difficult.

Regardless, it's important to decide how you feel about it and how helpful it is to your perception of your value and efficacy, as well as the outcomes you desire in your relationship with the organization. Good luck.

[0x008]

> I've found that a lot of people are really proprietary about documentation, (not even getting to architecture yet) and treat their time spent documenting as time spent giving away their negotiating leverage.

I have observed this also. I’ve even had colleagues voicing this explicitly to me. However, I think it is a little bit near sighted. A good manager will never assume documentation can replace a senior developer who helped build the system from the ground up. However, a bad manager might make this mistake.

But in reality I feel like there are two types of companies. The ones that understand that the experienced developers are their true capital and so everything to keep those with experience - and the ones who live under the illusion that they can substitute individual people with processes and organizational structure. Those will also let good people go instead of paying them what they are worth, because of “compliance” reasons or company policies and will pay a multitude of what the extra salary was in lost time and burned hours afterwards when the people who come after try to understand the ins and outs of the legacy system.

[throeawayDocs]

This is an interesting perspective that I hadn’t considered.

My colleagues all seem happy in their roles, although they work in countries with less workers rights/securities(?) than in my own country. Maybe they don’t document anything so they are seen as “sticky”.

However I do wonder how they would feel if they were blocked from taking a new internal role because they’re deemed too essential, because they’ve not documented anything.

[themodelplumber]

Yep, it's tricky...It could also be that there's a need for clarity, for example a minimum objective level of architecture documentation and test-passing... It might help take the pressure off of individuals who have a high personal standard of work, with little perceived recompense from the org.