Hacker News Reader

Comment by GoblinSlayer | Hacker News Reader

Then architect should tell the purpose of the tool to the documentation writer, otherwise the documentation will read "press Ok button to install %toolname%" that tells nothing how to decide what the tool is and does and whether the user needs this tool. That's the problem at hand.

View on HN

This isn't specifically the job of the architect. Any idiot can explain how the tool they built works. So the software engineer or the product manager can do this as well. Explaining how something works is not a magical skill reserved for software architects.

What is a skill reserved for architects? If you find yourself spending 100% of your time creating a powerpoint to explain things in a way that makes you sound smart and takes all the credit away from engineers then what you did there is a skill exclusive to architects.

The architect is the only idiot, who knows the tool as a whole and, more importantly, its role in the bigger world. Other idiots know only how bits are fiddled in a small corner of the tool on which they worked during their probation, they don't know the big picture, at all. In any case documentation in big companies today is outsourced to people with zero programming experience, and they obviously can generate only absolutely vapid text with traces of fuzzy associative connections with the topic.

So literally you’re saying the architect is the only person who can write good documentation.

Also the architect is the only person who did not write a line of code yet understands the tool better than engineers who work, code and solve problems across the entire stack.

That’s not only arrogant. It’s delusional.

He doesn't know how local variables are named, but what's needed for documentation is purpose and nature of the tool, and that's what engineers often don't know, because it doesn't help with bit fiddling. And a coding architect is an architect too.

Reply on news.ycombinator.com