Hacker News Reader

Comment by jlkuester7 | Hacker News Reader

> My opinion is that once an organization is a certain size, everything really needs to be written down and easily accessible. I shouldn't have to regularly ask people how to do basic things, it should be on a wiki. If it's complicated, it should be in a training video, or a user manual.

This %100. Automate all the things, but for any part of the process that cannot be automated/scripted, write it down. And don't just put it in some random Google Doc or Sharepoint where it is lost forever in the ether. Put it in a README that lives with the code or have a shared Wiki for the team. It need to be somewhere that is generally available, searchable, version controlled, and easy to update.

View on HN

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.

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.

Write it down even if it can be automated. And make sure the documentation is also comprehensible to people who don't already know how the system works.

Otherwise you're setting your company up for a miniature re-enactment of the Butlerian Jihad at some point in the future.

We call it Data governance and Enterprise architecture, those are fields and we're hiring like crazy

Reply on news.ycombinator.com