5 ms·
I've often thought that the need (and compensation) for senior engineers is partly based around their historical knowledge of systems and business logic. If yo
by jorblumesea 7y ago
I've often thought that the need (and compensation) for senior engineers is partly based around their historical knowledge of systems and business logic.
If you lose a senior, not only do you lose a highly skilled individual, you also lose institutional memory. Documentation can help some of this, but is often not enough or does not capture reasoning behind technical implementations.
Senior engineers are often living repositories for business logic and company knowledge.
- pm90 7y ago> Documentation can help some of this, but is often not enough or does not capture reasoning behind technical implementations. Doesn't that create perverse incentives to not create documentation?
- spockz 7y agoThis is a read vs write optimisation trade-off. If a senior engineer would need to write down all it knows and all things that were considered for a specific implementation or project he would have to spent a lot of time writing. Especially if the writing needs to be clear for some junior just joining the company. If instead, only the high over view is written down the person can be relied upon the fill in the nitty gritty details without having to spent years writing. (It can also be of course that we just lack a sufficiently efficient fork of dumping our mental context for others to digest.)
- yoz-y 7y agoI think there is also a problem with too much documentation. If you want do document too much, the docs will get too tedious to read and crucial information can be missed.
- perl4ever 7y agoI started working in a kind of non-technical department, and someone had developed a procedure for making some database updates which used to be done manually through a web page, and the procedure for this "automated" method went through like 50 pages. After doing it two or three times I'd memorized it. But if I was documenting it, I would be like "here's 5 bullet points" and they would be prompts to fill in the details. It depends on the audience, but the way I prefer to write documentation is I think of how I discovered all the stuff that was not obvious and try to provide starting points to each area of knowledge. In some environments, people will write so much documentation that you can't see the structure, and when you see repetitive sections, you can't tell what the difference is without actually diffing it. There is an enormous amount of formulaic documentation that is 90% boilerplate and almost completely fails to focus on what people need to know. So many tools have been developed to easily produce stuff that looks like documentation but doesn't have any content and then using them is compulsory, but substance is not. I've been unimpressed with the Microsoft online documentation I've had to look up recently.
- yoz-y 7y agoIndeed, I really dislike java doc style of documentation which forces you to explicitly state a short description, then parameters and then a return value. For many simple functions a return value documentation which mentions the parameters would be amply sufficient.
- 100inengyears 7y agoDocumentation is enough if you actually allocate time for it. All problems in software come down to rushed jobs or cheap hardware. And then these problems are compounded with no documentation on how the system currently runs. So now what you have is every time a problem happens there is some time taken up by relearning the structure around the problem. If you document you will usually see the problem happening. eg: This report generator runs every 15secs for every customer. Currently at 500 customers we probably want to shard at 750 customers. I bet the seniors at most companies harp about documentation because of the exact reason that they dont want to be the institional memory. They rather think about fun things rather than store all the ugly rush bs code. Or I bet they have their own personal docs because they want to keep that job security to themselves. The most challenging thing in software is dealing with the fact that there are humans involved.
- mooreds 7y ago> Senior engineers are often living repositories for business logic and company knowledge. I've definitely seen that. I agree that documentation can help with this, but you can't document everything (unless you're working for NASA. I have a friend who works for an aerospace company and they do a lot of documentation). This also has an effect on your compensation. If you've been at a company for years and have deep knowledge of the domain and the software, you're more valuable than you might be on the open market. It's interesting to me that (typically) the company doesn't recognize this and compensate you appropriately.