Hacker News Reader

Comment by metafunctor | Hacker News Reader

Even if it's all documented with a README, with container images and Ansible playbooks or whatever to make it all happen… still people will be complaining that it's oh so complex and that's not how we did it in my previous job and what about secret management, or load scaling, or full disk encryption, or how would this be deployed to a moon-based server, or whatever they can think of how the probably less-than-average crap you've built isn't maximally convenient for them.

So, even if you have everything 100% automated, most people will look at that and conclude that your automation is complex legacy bullshit and you should have automated in some other way.

Just saying.

View on HN

I second this emotion. We have spent years and countless hours investing in documentation and automation as we re-engineered a very large legacy application into cloud based technology (AWS). The application and supporting CI/CD pipeline is far better documented and supported than most and all of the underlying technology is within 5 years current. There are video based tutorials on nearly every aspect of the platform and machine images to accelerate development environment setup. Yet still, people new to the development pipeline will hand wring over "tribal knowledge" and "deployment complexity". News flash, anything constructed to support hundreds to thousands of business processes and millions of customers is more often than not going to be complex. Sometimes you just have to roll up your sleeves and try to improve the trail for those coming behind you.

> video based tutorials

there's your problem.

Seriously. I hate "video tutorials" on how to do technical stuff. I read faster than videos can explain stuff, and with text I can go back and forth to the stuff I need without trying to forward and reverse a video to a certain time.

The feedback is totally fair. What we do is conduct live "learning sessions" with experts in aspects of our implementation that go through tutorials on specific technical aspects of the platforms. These learning sessions are recorded and referenced next to the text based documentation that complements inline comments in the code. They are not a replacement for the text based documentation. Think of them as equivalent to various YouTube videos you might reference when learning how to do something. You might read the particulars in a piece of documentation but then also watch a walk-through of a specific piece of technology if you find that helpful.

Videos can be as good or bad as documentation, it just depends on how thorough the content is.

Possibly I am an old fuddy-dud but if your engineers prefer video tutorials to written docs I think you might have hired the wrong engineers.

I will say that things like secret management and FDE are likely policies that people are forced to follow and not things they directly want to implement.

Reply on news.ycombinator.com