4 ms·
The more experience I get as an engineer, the more time I spend writing documentation, proposals, tutorials and the like. This article is absolutely spot on wh
by simonw 7y ago
The more experience I get as an engineer, the more time I spend writing documentation, proposals, tutorials and the like.
This article is absolutely spot on when it points out that these skills become increasingly important as the size of an engineering organization grows.
The biggest challenges in engineering at scale (scale in terms of complexity and size of the team) are around communication. Good writing is how you scale your communication, especially if your team aren't physically co-located.
I don't think software engineers talk about or think about how to improve technical writing nearly enough.
- mdorazio 7y agoAbsolutely. And if you ever want to strike out on your own and start your own company (especially if you want funding for it), writing well is critical and can't always be outsourced.
- dsfyu404ed 7y agoA good tutorial is it own documentation and good documentation is its own tutorial. I've yet to find anything that packs a bigger punch than screenshots annotated with MS paint paired with concise description.
- bongobongo 7y agoThe problem is that many organizations prevent their IT/engineering departments from professionalizing in a way that would allow for this. "We need a month to iterate over requirements and specification" can land like a lead balloon in any project management meeting, because the _non_-engineers don't see any value in it.
- aphextim 7y agoWhen you try to explain to them that implementing a new system they want isn't as simple as installing new kitchen cabinets. Try to explain that it is like when you install a kitchen cabinet and then open up the door and it leads to an entire new kitchen cabinet set which also needs to be worked on and that cabinet also has it's own kitchen cabinets that need redone as well. A lot of times (at least where I work) management has a hard time seeing all the layers in the IT systems they use and what appears to them as a simple surface fix/change isn't always the case.
- tetha 7y agoI'm more on the operational side, but I have the same experience. I easily spend 50% of the time I spend on technical topics documenting my findings. To us, good, structured documentation and/or well-written tickets are a crucial part of delegating a task. Practically, it is part of my job to figure out and solve hard and architectural problems, around once per problem. Then I can document it properly. After that, the bulk of the team should be able to solve this problem. And this is producing value for our customers, because well-documented standard tasks are resolved faster. I might be unavailable due to some critical problem. But if it's a documented standard task, one of the four other guys can pick it up and resolve it quickly.