Hacker News Reader

I'm that guy in my current company. When I get brought in to an existing project, the first thing I look for is the README. To my disappointment, it either doesn't exist at all, it's the default generated, or it's 1 or 2 years outdated. So during project on-boarding, I document everything I can, create or update the README, then commit and push to the repo.

In all of my coworkers across all projects, I'm the only one who does this. I'm pretty sure nobody reads them either. I don't mind though, it has paid for itself countless of times already, since I always reference it.

Honestly it is so frustrating for me when I have a new project that is written by someone on my team and I need to do something to it and so I go to view the repo in Github and everytime without fail there's never a stinking README.md and so I have to go message my coworker on teams and harass them to help me figure out things about the project that 10 minutes of writing some basic documentation could help.

I want to be that guy that document everything, because I have seen the need for system to be completely documented. however, every time I start to document some system or code the info change or I'm away from it for a small while and the documentation and the system drifts apart.

Exactly. Documentation is expensive and time consuming and needs to be maintained. They're absolutely great to have and can be vital, but it's up to management/leads to prioritize it because, at the end of the day, they decide where the money and man hours go.

This. Good documentation could easily take much more time than an actual implementation of a feature / system and what is an initial X days/weeks/months of estimation is not swallowed as easily by (some) management when you tell them it should be doubled if quality documentation is desired.

there are dozens of us!

> first thing I look for is the README. To my disappointment, it either doesn't exist at all, it's the default generated

Auto generated READMEs (and their handcrafted equivalents) are worse than useless. Not only are you wasting your time creating one (and giving yourself the sense of having accomplished something when you haven't) but the effect of a README creation is one-to-many, so consider that wasted time and then throw a multiplier on it. That's the cost of a dummy README. Don't create them, people.

Building a culture of documentation starts from the top.

Today our 40 person org has 1,337 knowledge base articles (as of yesterday, a coincidence, and we probably have a different number today).

It started with myself (CEO) creating all of the initial documentation.

3 months after my first employee joined, I started holding her accountable to creating and updating documentation.

It's not a one time thing.

You can't say, "your job is to do documentation" once.

It's consistently talking about it.

It's scoping in documentation updates and refreshes into bi-weekly sprints and quarterly goals.

Once she was onboard, we began to hold everyone else in our organization accountable too.

Again, it's never a one time thing to get anyone bought it.

It needs to be constantly discussed and scoped.

Today, all of the managers are bought in.

Instead of me explaining the importance of documentation, it's our org's managers embodying and instilling the culture of documentation into everyone new.

They understand the value of having their reports check the KB first.

They understand the value of being able to link someone to a KB instead of repeating themselves.

They understand the value of being able to work more async.

They understand the value of not being a bottleneck for someone else.

I stopped spending much time creating documentation about 6 months ago - and the number of documents just keeps increasing.

Today, I'll push documentation forward for new position / roles.

I'm working on delegating finance - and spent a bunch of time putting together documentation on how to handle the company's money.

- Expense policies

- Org software purchases

- Invoicing and payroll

- Phishing and security

- etc

When I was first sorting this out, I realized that I shouldn’t be repeating things from the documentation, I should just be linking to it.

It’s a mixed blessing. In that case, the people who peppered us with questions slowly learned to find answers themselves. On the flip side when people ask you questions you get a better idea of what’s going on elsewhere in the project.

Later though, when it turned out we had a bad batch of hard disks on our dev boxes, the setup docs went from pretty okay to complete.

This is great advice. My father-in-law recently passed and my mother-in-law literally knew nothing about their finances. She's been calling insurance companies and banks trying to make sense of it all. This is more an indictment of their lack of communication over the years, but the principle still stands.

My wife asked me to write out on a piece of paper all of our bank, investment and insurance account names, numbers and passwords just in case I died during my last business trip.

Get a password safe and put everything in it. Share the password or use a password manager with sharing.

I still probably need a technical executor for some of my encrypted stuff as that's a little more complex.

I use 1Password for this purpose essentially and I’ve printed out backup codes and put it into an emergency box. One other problem is that the MFA every other site has now with SMS means that in a disaster recovery situation one will need access to the original phone number associated with an account when logging onto for the first time on a new machine. So this means a shared voice / SMS capable account is also necessary in conjunction with e-mail to avoid more complications. I realized with Apple’s system if I lost all my gear on a trip that nobody would be able to login to my Apple account because all my devices would have been lost.

Like any backup plan, unless it’s regularly tested it should be presumed to not be working

Can't you port the number to something like Twilio or Google Voice in the event you need to get SMSes to it? Or get a new SIM card with the number and toss it in an old phone.

Lots of these don't allow the use of VOIP-like numbers.

Apple just announced a couple new ways to handle this, coming this fall.

https://www.macrumors.com/2021/06/08/ios-15-legacy-contacts/

Bogleheads has a great thread on what goes in your Death Book.

https://www.bogleheads.org/forum/viewtopic.php?t=119346

I strongly recommend that everyone with or without dependents look into disability insurance. You are much more likely to survive an injury or illness and be unable to work, than you are to die.

How reasonably priced is this to buy individually?

The short answer is "next to nothing" especially for tech salaries. I did a generic search and questionnaire to see what actual quotes were. For a 35 year old non-smoker male in my zip code, with an office job, $84/mo gets $6400/mo in benefits if I become totally disabled. There's a ton of caveats (90 day waiting period, 10 year term benefit, medical exam etc) as with any insurance product. You can get partial disability insurance as well (this is total only).

What you really want is insurance that pays out if you cannot work in your given profession (e.g. software engineering) not insurance that only pays out only if you can’t even work as a greeter at Walmart. I’m under the impression that this is very expensive because of adverse selection effects.

This is called "own-occupation" (as opposed to any-occupation) and is more expensive but not astronomically so.

It looks like about $250-$400 for a policy I would want. That’s not unaffordable but it’s not trivial either. Anyway, thanks for the nudge.

When I last looked into it, a good own-occupation disability policy from a highly rated insurer like Guardian ran about 3% of your salary ($3000/year if you make $100k). Could I afford it? Of course. But it’s not a no brainer like a cheap term life policy is.

I ended up passing and my only protection right now is the disability insurance offered by my employer. Experts say these policies are almost worthless, but they’re better than nothing.

At that point you're probably better off investing the money and hoping you don't need it in the first ~10 years. Even if you need to invest more than that 3% to get the same "cover", if you don't end up disabled you can use it for an early retirement. The money spent on insurance is gone forever.

The math doesn’t work out. If you save 3% of gross starting at age 22, get 8% returns, and target 50% of gross for disability income you only cross the threshold to make it to 65 at age 56.

Like all true insurance, we’d expect disability insurance to be expected value negative but this isn’t something it’s practical to self insure.

Hmm, pretty certain we're all guaranteed to die, but that doesn't mean that we aren't also likely to survive some serious accidents or illnesses and possibly need disability insurance before that point. I was run over by a Mack truck biking to work about a decade ago, short-term disability was handy for the ~9mo it took me to be mobile again.

That sounds dangerous, I'm glad you got better

> just in case I die and my family has to figure out the intricacies

I'm reminded of how so much of what we know about history is because of the diaries and correspondence that happened to survive to the present day. There are surprising gaps in what we know about day-to-day life in the distant past because nobody bothered (or was able) to write it down.

To be slightly flippant: we get even more valuable information out of garbage dumps.

People usually bias their writing towards what they consider to be important information. And they leave out what they consider obvious context.

So we have a lot more information about battles and kings, then about daily life.

People are less biased towards highfalutin in the ways they produce garbage.

This is a very wise observation. The most important things are always the ones we think are so obvious that we don't mention them.

Battles and kings are not garbage.

Kings are definitely garbage.

I was talking about literal garbage dumps. They are incredibly important for archeology.

Battles and kings and things that seem important when they are current, but aren't as interesting in a few hundred years as insight into daily life.

No, but all the ancient historians wrote about battles and kings, so we have that info all written up already. Very few of them wrote about the life of the average peasant, so to find out about that, one of the richest kind of archaeological sources are literal garbage dumps: https://en.wikipedia.org/wiki/Midden

Whenever I hear people complain that our digital media won't leave much for future archaeologists, I always think of our enormous output of plastic, metal and glass garbage.

Other places that tend to provide this sort of information are tax records and wills, both of which tend to be somewhat likely to survive. Even if you can only see tax laws it can tell you a lot about how the society fitted together.

> I had already started internal blog groups and was encouraging people to write.

Can you give some advice around that? Was it one blog in general, one per team, per person? What tool did you use for it? What else do you think is notable about it?

For the blog part, it was a simple Multi-WordPress Setup. The idea was that anyone could start writing independently or as a collective and can be made private or public. It became rather evident that most people were comfortable writing in groups -- engineering, marketing, future-tech/R&D, etc. Initially, I started writing pretty much weekly, and then the crowd picked up.

The notable thing about the system was that people began to know their colleagues better, discover stuff together, and partner up to do interesting experiments.

Before that, I started by writing fortnightly newsletters to everyone in the company. It was just what happened in the last two weeks. I was just the messenger. I highlight designers, developers, DevOps, QA people, etc., with snippets of their exciting work. It became an instant hit.

I'm not particularly fond of managers/leads who do the talking for what their team or juniors did. So, I had to bring in that culture of every doer doing their talks or bringing them to the forefront. The only way to start that was to write to everyone who did what last week. Now, when I get in that junior developer to talk about what he did, his thinking behind it in the next meeting, people know and are prepared. Also, even if some managers/seniors continue to talk over their junior team, people already know who did the work.

That's excellent advice, thank you!

‘always be dying’

I dig that saying. It’s a sad thing, but a good developer should make themselves obsolete by the end of their run. It’s our form of ethics.