A few years back, I had the opportunity to lead the Product Team of a 200+ people company. It took me over a month to understood who does what, and I tend to try to know things around me and at least have the idea of “what to do in an emergency.”
I stumble on one DevOps guy who wrote every bloody thing happening in the system. He likes doing it, but from the way people were asking questions in the common chatrooms, group emails, I knew nobody read them. He loves plain text, nicely formatted with the old-school Unix-styles et al. I had talks with him outside of work and found him fascinating; I asked him help with my hobby, home-lab tinkerings, etc.
By that time, I had already started internal blog groups and was encouraging people to write. And indeed, a lot of people came out to write about engineering, marketing, product, and it became a routine for people to show off what they can do, what they love, and what they are good at.
In one of my regular company-wide emailers, I dedicated a big piece to the DevOps guy, pointing to his work and the beauty of his documentations. People loved it, and they began reading it. He remained a friend. That mailer was the only way I could highlight people I encounter doing good work, to the whole team up to the CxOs.
By the time I left the company, I was responsible for many vital things in the company, but I could transition everything smoothly with the documents and credential details (thanks to 1Password).
In the last year or so, I have been thinking more about -- always be dying. I think the similar vein of Always be Quitting; I try to document, write out details, just in case I die and my family has to figure out the intricacies.
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.
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.
> 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
> 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.
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.
What does one do when they live by this philosophy of documenting everything and making sure knowledge is captured, but your team mates just refuse to volley the ball back? I find myself documenting how the software works, writing up proposals with beautiful diagrams etc, but my teammates won't take the simple step to even read the dang thing without scheduling a meeting with me to spoon feed / read it aloud to them.
That happens quite often, indeed. My theory for this works as follows:
1. People do not have the time (or think they do not have the time) to read documentation for more than 5min by default. They need to consciously allocated that time.
2. C-level types generally do not read details IMO, presumably because they think they won't understand it anyways. (thus, "executive summary")
3. Everyone who aspires to become C-level someday copies this behavior and ignores all but the "executive summary".
4. Otoh, C-level types are always in meetings. Thus, aspiring career folks will copy this behavior, too and only ever focus on something if they are in a meeting.
5. This culture of only ever sharing information synchronously is somewhat infectious and will spread throughout the company.
6. The behavior is also self-enforcing. If several people are in a meeting-only mode, you can only get them information by scheduling a meeting yourself. This will, step by step, bring you into meeting-only mode.
7. In the end-game the whole company slows down because information is spread only by the speed of meetings.
The worst thing about this, IMHO, is that we had a chance to change this with the shift to remote work, but what happened instead of switching to more async-first and written communication styles, was that everything was moved to Zoom/Teams/whatever virtual meetings which IMHO are even worse than in-person meetings.
I also believe that many people, including developers, actually don't have very good reading comprehension skills. Obviously, this doesn't apply for most people who comment on forums such as Hacker News, but in general I believe that it's true.
Estimates of the literacy level of the adult population are doubtless wildly over-estimated. There's a reason that newspapers are targeted at a seventh-grade reading level, or at least used to be.
Writing skills are even more depressing. Just laying out bullet points coherently puts somebody in the top quartile of white-collar workers.
> Just laying out bullet points coherently puts somebody in the top quartile of white-collar workers.
I feel like a relatively intelligent person but I absolutely struggle with writing concise emails / docs that are well organized. It's an agonizing process and I feel my results are hit or miss with little inbetween.
> Just laying out bullet points coherently puts somebody in the top quartile of white-collar workers.
To be fair, that's not my forte either as my writing tends to be sort-of meandering at times. Just recently I wrote a longer message to my PM and he told me "yo, bullet points please".
The literacy and writing of my colleagues has always been good, but sometimes it's in a different language, and their English literacy and writing are not as good.
There's definitely a problem there in that we often assume that "fluent in English" means "mastery of the language", but these two are different things.
I'm often firmly in the "this meeting could have been an E-mail" camp, and have sadly sat through my share of those. Unfortunately, often the reason this meeting isn't an E-mail is because the people who need to know and need to act don't read their damn E-mail. Or they don't read it completely, or they read it and don't comprehend it, or they read it but don't take the needed action, or for lots of other reasons. I'd love to treat people like grown-ups and reap the benefits of purely asynchronous office communication, but it's so rare that this happens.
My method now is as follows:
1. Send the E-mail asking for whatever, and an expected time frame
2. If I don't get the requested reply or action in the time frame, gently ping with a chat message
3. If still nothing... Well, here we go: it's meeting time, regrettably
I also never fully understood this problem, but the other day, someone shared their screen and I saw, I kid you not, 5000+ unread emails. Granted, these were both private and work emails, but still.
I think when something like that happens (and I don't think it's an isolated case), we've completely lost the ability to deal with email in any sort of non-random way. There's a couple of questions I would ask myself there:
- Why am I being CC'd on so many things? (unfortunately, this can often be outside of one's control)
- Why don't I use automatic filtering and tagging?
For 1. (for me) I think the ever present feeling of having no time to read documentation stems from being in a desktop support role and an ops role. If the phone's not ringing - it has a good chance of ringing any moment. There's also monitoring all the things I'm expected to monitor. Those build in a kind of moment to moment thinking that outright stops deeper thinking.
fwiw - As a lead engineer I tried to influence meeting formats as being "review only". The idea is to distribute ideas as wiki or markdown prior and review/comment prior to meeting. It failed spectacularly. I believe the demands of multi-tasking (meeetings, chat, meetings+chat+work at the same time) have caused a lot of people to not have the will power to sit and read. Reading is considered "not-productive" when you can just go to a call and ask the person to explain.
Express this dismay to them, in a honest open conversation. Discover what holds them back. Be open, don't scold, maybe they reveal a problem in your attitude as well.
> Express this dismay to them, in a honest open conversation. Discover what holds them back.
Been there, done that.
The popular answer was that projects change too fast and he doesn not have time to maintain docs.
However, I firmly believe it all boils down to internal competition, and a refusal to give away to team members the knowledge they had to build up with their work.
Knowledge is power, and not disclosing how things work and why they worked is the key attain and preserve value within the team. You are a big shot if the things you do are hard and no one else can pull them off, and you achieve that by not giving away the information that allows others to easily do what you do.
There’s the occasional engineer who works this way, but I find it exceedingly rare.
A much more common pattern (though still not that common) is the mentality that they’re focused on high impact work, and documentation isn’t it. Selfish, maybe, but not outright malicious.
An even more common scenario (that covers the vast majority of cases in my experience) is an internal culture that values shipping above all else, and makes engineers feel harried. Even if documentation would reduce busywork and improve productivity long term, management is too focused on the short term challenges to see it.
As a team lead I would not except this kind of toxic gate keeper mentality. A single person with such a bus factor is a huge problem to a teams/projects (or God forbid departments) success. Discuss and frame it in terms of worries for business continuity with your line manager. If that does not click, consider it a red flag.
> The popular answer was that projects change too fast and he doesn not have time to maintain docs.
This is the problem I have clients will change their mind on core functionality from day to day with no understanding or consideration for how this constantly changing spec creates development hell.
I try talking to the client management but they also have no understanding of development. When I explain it to them and try to educate them they use their lack of understanding as an excuse to not try to understand.
Eventually they get the point but then just argue that its difficult to explain that to the customer and manage the customers expectations. I think yea no shit its difficult to explain to some one who doesn't understand but it is possible I just demonstrated that, now go do your job.
If they don't want to do their job they wont and no amount of polite talking to them will change their mind on that. If I eventually call them out on it, the hour I spent patiently explaining and reasoning with them is just ignored and I get called out for having a bad attitude.
At the end of the day the client management's only accountability is to the client so they just say yes to anything the client says, if that causes developer hell forever then thats the developers problem not theirs.
> The popular answer was that projects change too fast and he doesn not have time to maintain docs.
I sort of agree with this, but rather from the perspective that often the effort required to maintain documentation isn't in proportion to the payoff.
Naturally details differ among projects, but I find that the 20-80 rule applies to documentation, i.e. that 20% of the documentation provides 80% of the value. I find that focusing on stable architecture/properties of the system is a good approximation to the 'important' 20%.
If the system also has any especially tricky parts (e.g. a transaction coordinator) warrants documentation, but that also probably falls under the 'not subject to rapid change' 20%.
I'm assuming project internal documentation here. If you're documenting things for customers, then you'll want to document everything very thoroughly, but one would hope that people figure that out eventually when support tickets keep coming in...
As a programmer with ADHD, I'm actually the documenter more often than not: my memory is very volatile, and I don't want people to interrupt me, so I prevent it by giving them the information beforehand.
Or maybe they’re just not that smart or have mental bandwidth? I’m surprised more people don’t acknowledge that a lot of engineers in a lot of companies probably have at best average IQ if not lower.
Let's assume this was true. Are you saying colleagues with lower IQs shouldn't have been hired?
If so, I would be careful about coming to work thinking that many of my colleagues shouldn't have been hired. If that's actually the case, you're just in the wrong company and you should bail. Caveat: maybe you'll find your new colleagues lacking too, if you think that's widespread.
And if that's not the case, then you have to work with the colleagues that you have, regardless of how smart you think they are. And it's frustrating sometimes but only because you're thinking about the imaginary colleagues that you think you should have.
I think its more about trying, I think I have average or lower IQ but I try really hard to make up for it. I frequently see my colleagues say I don't know how to do that as if it excuses them from trying.
The same point applies though: if if you think a large percentage of your colleagues shouldn't have been hired, that's one thing... If not then you have to just make do with your actual coworkers. To the point of the root comment, it's no use deciding that you're done with your share of the work (you wrote the docs after all) and now it's up to others to do their part (why are they so lazy!). That's just fantasizing that you had different coworkers, and it leads neither to effectiveness nor to happiness.
I can’t speak to what my IQ is, or whether I learn faster than others, but I can, at the very least, say that I’ve put effort into everything I know.
So when something needs to be built as a Vue.js component, or we need new build scripts in our local environment, or a SQL query is slow, I learn what I need to and I do it.
Everyone else just throws up their hands and says “welp, I don’t know JavaScript” or “I don’t understand this old SQL”, as though they were born with the knowledge they have and will never gain any more than that.
Or maybe the next one will be much better. This actually happened to me. New company was a god-sent. Instead of most colleagues being the "throw arms up in the air at any slight complication and do nothing" I got wonderful co workers that both love their job and are good at it.
It is so great to finally have found other like minded people that you can just have an awesome discussion with on an equal enough level. Of course people still have differing opinions or knowledge about specific topics. We can have a heated discussion on what the best structure or naming is for something but you don't have to fight over whether naming is important in the first place and you don't constantly feel like you have to explain the basics on everything over and over, never getting anywhere.
In general, people who do most work tend to keep everyone around them hostage. People usually lack access to even basic stuff and nobody builds the organisation, usually.
The book The Unicorn Project shows how it is dysfunctional. Leaders tend to thrive doing nothing of value in such environments.
I really like this mindset. It's compassionate toward your co-workers and would make your entire team more effective. And best of all it's accepting reality and would make you happier too. Thanks for this.
The thing is, these kinds of organizational problems are almost NEVER about people not being "smart enough".
It's not uncommon to have utterly dysfunctional workplaces where the people are all very high in IQ (1), have premium academic credentials and stellar career trajectories. What matters, far more than raw intelligence, is people not behaving like assholes.
If people aren't reading and sharing beautifully prepared internal documentation, it's more likely to be about their perception of status about the author or lack of openness to new experience. A lot people are just incurious or are obsessed with their status. They tend to "punch downwards" and don't handle change well (or at all). This has little to do with IQ.
(1) We don't really know IQ do we? Unless it's measured we can only guess. When someone says that somebody has a high IQ, usually, it just means they perceive the person to be erudite or learned, acheivements, clothes, speech, vocabulary, appearance, credentials, titles-- all these things feed into that perception, but usually NEVER the score of a f-ing standard IQ test.
my reading of a lot is always more than 50%, which implies to me that more than half of the engineers at half of the companies have average IQ or lower - which seems unlikely.
on edit: unless of course we assume that development / engineering type careers attracted more people of average IQ or lower - but I think that will be a hard sell on HN.
> my reading of a lot is always more than 50%, which implies to me that more than half of the engineers at half of the companies have average IQ or lower - which seems unlikely.
That depends. It's unlikely that they have at most the average IQ of the general population.
But if we assume that engineers as a group are smarter than the general population, it follows immediately that over half of them are below average among engineers. If you mostly work with engineers, that will probably look like "below average".
> But if we assume that engineers as a group are smarter than the general population, it follows immediately that over half of them are below average among engineers.
Well, depends a bit on the shape of the distribution, because of mean vs median. But you are right enough for most reasonable distributions.
That's what the word "most" is for. A lot only means something like "large amount", with no hint at how large. It could be more than half, it could also be 1% because that's still a lot of people.
yeah if there's a context to a lot, as per the previous example of homicides, you can understand what a lot of homicides will be in relation to homicide rates in other places.
So if you don't really have an easy to understand context I don't know if 1% would be considered a lot.
Let's imagine the HN conversation:
a lot of people love the fruitcake they receive for Christmas!
I checked Santa's bureau of statistics - only 1% love fruitcake - is that what you call a lot?!?
So I guess I agree a lot doesn't have to be more than half, but when I don't have an easy to identify context I read a lot as being most. Surely my mistake, but one I feel is hard to guard against.
I guess the point is that if some people need to put in all effort just to deliver the required thing, while others can deliver the thing and have 20% time left, the latter people have much better time to do documentation.
So you say, why not plan for more time to do the task? Then the people who had 20% capacity for documentation etc. now have 40% capacity for that plus other things, and the same annoyance happens for the other things (e.g. unit testing, automation, etc.).
A good solution requires the company and the team to do the difficult thing and recognize and allow for the fact that different people spend different amounts of time on the same work.
And so they use that 20% to write documentation or do they move onto the next required thing? But here I think you’ve stumbled upon the root of the problem:
Documentation is the required thing.
Developers should slow down. Knocking out features is not the be all and end all.
Perhaps their goals aren't aligned with yours, and perhaps yours aren't aligned with the company's needs. If the job gets done well enough without all the documents and pretty diagrams, why drag your coworkers through all the unnecessary ceremony wasting their time?
I just write documentation because I know future me would like to have it. That is just good engineering.
If you are an electrician you also label your terminals and add plans to avoid troubles for other electricians and your future self. People who don't do that are handymen, but not electricians.
Yes, and the electrician doesn't insist on everyone reading all the labels and plans on delivery. They are meant to be references, used at a future time they are needed.
Documentation is there to help you understand your project now. If you’re using documentation only as a historical reference then you’re using it wrong.
Documentation is there to help you (or someone else) understand the project that you haven't been working on for 6 months and it goes back alive. You'll be very happy to have things written down: nobody will remember why this thing does that, or how to restart the damn tool.
Yes, and it's also there to help you now. I think a lot of people in this thread are underappreciating the art of writing.
When you write your thoughts down, you can then read them back to yourself. Then you can see all the flaws and gaps in your thinking. Then you can edit your document to refine your thinking. And if you work on a team, you can then share this best-representation of your thoughts with your colleagues and get their feedback. If you're not doing this then you're almost certainly not creating optimal designs.
Maybe you think this is all overkill, and maybe it is some of the time, but I can't tell you how much stupid code I've read that was written by smart people who weren't thinking clearly.
You can get any development project done without documentation; I don't think that's up for debate. The question is, can you make changes to this project, improve on it, explain it to another team during an acquisition or due diligence: 5+ years down the line? And if you can, will that new development timeline be accelerated if you had documentation and diagrams to work from?
What happens when a new CEO comes in, hires a new Engineering Manager, and 85% of the devs quit in protest? Will a new team be as effective as possible without that documentation?
In my experience the above scenarios are quite common in start-up and "scale-up" size companies. Where there are a lot of things in flux and nobody has a plan 5 years out. Then, lo and behold, it's 5 years later and everyone is stuck picking up the slack instead of developing new/improved products.
And you're right, it can be a case of misalignment of goals and vision; not everyone cares about the long term. But if your company isn't thinking of problems further out than 6 months then you might have a different problem to address...
I would refuse the meeting until they have at least attempted to use the resources you provide. If they do and still have issues, you can talk with them about what may be holding them back from using them effectively and make some changes on your end.
It's about firm boundaries. I remember reading a story on r/TalesFromTechSupport where the OP put down his foot about an older lady not googling things before asking him simple tech-related questions. At first she was annoyed, but after learning to Google effectively before coming to him for harder question she learned a valuable skill and later thanked him for setting those boundaries.
Your goal here would be to make it easier for them to search than to ask.
Have a generic link in which they could find most of their answers. When they ask something that's in the docs, reply with a link. When they ask something that's not, add it to the docs, and reply the answer + "that was missing - I've just added it to the docs" to reinforce the fact that this time it was OK to ask and that they helped you improve the docs.
The more someone asks you things that were searchable, the more you delay the answer with the link. If you make it quicker to search than to ask, that'll encourage them to search.
If they still don't change the attitude, let your manager work. If that doesn't bring any other change - it may be time to move to another team/manager.
The problem (with the teams I've worked with, at least), is that you have multiple tools for documentation and you generally get overwhelmed and stop even trying to search.
This points to the cultural of the community within the company. Culture is difficult to create, maintain, and explain to others who are new.
I've had the good fortune of working with two groups of people who valued the idea of public documentation on an internal wiki. While some of the documentation was not rigorous in terms of requirements, functions, and detailed development, but it was enough to scope the issue. Each project had an operational section within the wiki which became the living maintenance plan for that part of our services. It was wonderful.
Upon selling my last company, the acquirer didn't get the concept of the Wiki and that everything was in there. Eventually one of my employees printed the wiki and created eight copies of a 4" thick binder and sent it to their office. Ten years later I'm told that their engineers love the binder and call it the "tome." My teammates and I chuckle about that, but at least it's being read.
I know what you mean. I have been there, I am still known as “have you checked docs” guy in some circles.
Now I am older and wiser. My advice is don’t document. This is cultural problem that needs to be solved at much higher level. If leadership doesn’t care then nothing will change and you will get labeled as asshole. Just flow with culture and you will be much happier. Or find a new job.
I agree. If you do something for others and it is not appreciated stop it. You could still document for yourself. Before you leave write about 20 words what could be done for the next working day, for example. Have a log of these leaving words then it becomes a diary of work. Just find out what works for you.
First and foremost you should write docs for yourself. They need to be short, concise and practical. You only get there by using them yourself. All the long-winded, theoretical C&C docs in the world won't provide enough actionable signals, as its mostly noise. Even if it covers everything elegantly, in your mind.
You should get feedback on docs, even if just from yourself. They shouldn't be a drag to maintain. If you don't eat your own dogfood or use them to keep people hostage, they won't help others figure out their own responsibilities.
If you don't build a culture around docs, its mostly waste. Often nobody even finds them, have the access/introduction to make it meaningful, and they are not open ended or written for practical usage.
It's interesting to see someone come out and just give this advice, but there are a lot of teams where that really is the correct call. Well written documentation can be helpful, but your documentation is extremely unlikely to have much of an effect at all. It would be one thing if it was a lot of work for marginal improvement, but if there's ZERO impact, what's the point?
People will likely never know it exists, or read it once, get frustrated that the information is tough to parse, then give up, and go to a meeting. It's especially annoying, because in my role most of the information actually is in the docs. They want me to figure out what information is important, and just put that in the documentation. So they want me to create a greatest hits compilation remix of 5-10 other documents with just the important stuff... except you can't know what that is until you need it.
I haven't read your documentation so I don't know, but possible explanations:
1) Your documentation might be long-winded and they want a guided tour or executive summary, or at least a 10,000 foot view from which to start
2) Maybe they don't know where to look for what they're looking for; if you've documented a bunch of functions but provided no curated guide for what code exists and where to look based on a use-case, it might never be found
Your documentation tree needs to be written to be skimmed, because the search functions are never good enough to let people find the bits they’re looking for. Either they are new and know nothing, or they’re looking for some old info they can’t quite recall. They aren’t there to read for pleasure, so don’t presume that the existence of documentation is sufficient for people to be satisfied.
It’s not enough to write the docs, you have to organize them too, in a Wiki, and keep organizing them. It only takes a few hours a month. You can do it when you’re blocked, or finish your tasks a little early on a day/week and it’s pointless to start something new because you’re leaving for the day in a half hour or the weekend in an hour and a half.
The on boarding docs and the latest initiatives go on the first page, but as new things are started the old ones need to be grouped by conceptual area and pushed down one level. When those areas get too big, push down again.
When I tried to describe my process to someone I realized I was essentially applying the B-tree algorithm to our wiki, with the slight modification that all out of date docs are footnotes on the newest. Eventually all of the dated documentation becomes leaf nodes where people don’t see them and mistake them for authoritative.
You're not doing it for them. You're doing it for you. Following your own philosophy (whatever it is) takes an unshakable faith that it is the "right thing to do" even when nobody is watching. Like religion or sobriety, it is a daily struggle to follow what you believe. This is what leaders do.
This is nonsense. Writing elaborate documentation is useless if you already understand your own concepts. Software docs are one thing (comments and readmes) but elaborate documentation meant for knowledge sharing that is never actually read is just a waste of time.
Your sentiment feels more like "dig a hole, it builds character!"
What is "elaborate" here? I write out personal work docs in a wiki complete with links for cross reference and a semantic search engine. Is that elaborate?
I like that I often only need to ask a question once, and that I can delegate answering questions to the docs (where I've published subsections for the rest of the team).
Moreover, as someone with a bachelor's degree in Cognitive Science & Computer Science, I know from the literature and experience that writing things down improves your memory.
If I'm doing it to save my time and expand my memory, then it doesn't matter who else might read it.
No. Documentation is for the code or the project, for any reader. Proper documentation can be read and understood by anyone that needs to interact with the project. I don't know when it was decided that "documentation is for yourself" but I very much disagree.
Well, the spirit of quitting might apply here too - I've worked in environments exactly like yours, and I've worked in environments where I felt like everyone on the team put in their all or even that I was the dimmest man in the room (in a good way).
The quality of life on teams like that can make slightly lower pays even worth while, so always consider that your current experience isn't necessarily what all horizons look like.
Though sometimes frank conversation can build your team up better.
My experience too. I guess most people are just not wired to read documentation.
I love learning by reading, but most people just want to sit in a classroom and be spoonfed like you say.
I think it's also company culture, and most companies have a "let's meet and present slides" mentality. So as long as there is no meeting, there probably is no need for you to know.
> I love learning by reading, but most people just want to sit in a classroom and be spoonfed like you say.
To build on this, it's more than just being spoon-fed, it's being told exactly what to do, step by step.
I think this may have several causes, but one I can see is being afraid to take responsibility. "I've just followed the procedure! It's not my fault if it didn't work / brought the site down!". And this comes down to the local company culture.
Presenting a nice documentation, which is more general, although more complete, means that the reader must actually understand what the doc says. Now, of course, they may have been trained by shoddy docs that it's oftentimes an arduous, uphill battle, so they have a knee-jerk reaction to it.
But they also have to take responsibility for their actions, which, in a culture of cover-your-ass above all else, is a tough sell.
Lots of documentation is written by and for people writing it and not for someone who just arrived at the company.
And then you expect some junior dev to just understand everything without asking.
A culture where people are afraid of asking questions is worse than having the best possible documentation on everything
> A culture where people are afraid of asking questions is worse than having the best possible documentation on everything.
No doubt.
However, my answer was to someone talking about people expecting to be spoon-fed in meetings, not just asking questions about some points they don't understand / can't find specifics for / etc.
The dynamic is very different. Asking questions is active. You read, try to understand, realize you don't. You then form a question and ask it. Contrast this with someone who just expects a laundry list of actions. "Just tell me what to do [step by step]".
My answer was also from experience in companies where even people with seniority and who had been there for quite a while will expect a checklist-like procedure to do things, and hardly attempt to actually understand their tools.
I get that the mental model of some tooling is not always self-evident, to say the least. But it's clear to me when someone tries to understand it and fails, and when someone doesn't even try. And I'm talking about tools they use day in, day out. They just learn to click that button and to expect that result. When something goes wrong, they have no idea what may have happened. I suspect this may also be somewhat related with the discussion on HN the other day about error codes [0], as in they get so used to cryptic, vague or downright wrong error messages that they just don't pay attention to them anymore – because 9 times out of 10 it's a waste of time.
> A culture where people are afraid of asking questions is worse than having the best possible documentation on everything
Yes, true, but a culture of asking too easy or even dumb questions that the docs clearly cover is also worse than having the best possible documentation on everything.
One company I worked for got it right, IMO, and it stuck with me. My mentor told me the first day: “You must spend at least five minutes trying to answer your own question by reading the docs before you ask someone else. And you must go ask someone if it takes you more than ten minutes to find the answer. Do not ask someone without having tried to find the answer yourself, and do not get stuck on something alone.”
Well there are lots of cases where I would be wasting 2 hours searching through docs to maybe find something meaningful while my coworker has all the required knowledge.
I always ask. Isn't it stupid to waste time reading unnecessary info. (finding needle in a haystack)
I definitely understand this, but there are limits. A guy I worked with (super nice, hard working and a great engineer) would always slack me with questions that he had previously slacked me. In his defence, these questions were in my wheel house and were tricky things that he only have to do maybe once every couple of months. But when he was slacking me he'd literally say "hey man, I know I keep having to ask this but..." I eventually started responding: "Scroll. The. Fuck. Up.". The answer would typically be a few pages up. I even tried using the slack search for his question, and would find the previous time he asked. And yes, this shit was also documented in the git repo in a README.md that was alongside the code (so there was no "searching for the docs")
I spend lots of time reading and reviewing docs and I must say it's a daily reminder on how much empathy is missing in this world. Not a lot of people try to make the thing readable in any other sense than just spouting things on paper.
I often draw a parrallel with code, where once the unit tests pass, let's ship. Dear colleague, would you mind just editing yourself for your future reader or maintainer or future self. You're not that good that your first draft is enough. Edit until it's fairly understandable. Remove the hacks, reorder the text, remove all the TBD/TBC/TODO...
I feel you. A blocker I found is that typically everybody is down in the trenches of the actual project work coding, reviewing, analysing bugs, helping support. Therr is already something more urgent to do.
You need buy-in from your team lead/line manager and a critical number of team members that actually want to make a cultural shift, but for some reason cannot. Your regular team retrospectives are the place to address this and come up with an action plan how to bake it into teams processes.
One of the possible solutions is to block time in the teams calendar for dedicated "learning". That could be regular "developer forums" or "reading clubs" or what ever.
If a document is required to be read before a meeting, schedule 10min in the beginning of the meeting where all collectively read the doc.
I don't think blocking that time works per se, it requires people to actually stop what they're doing and work on something else, while they will probably prefer to finish what they're doing with that time or take a mental break.
Your last one (reserving some time in the meeting to make sure everybody's aligned) is pretty smart though. If that step is skipped, you may end up with half an hour of repeating what is in the doc already.
I feel your pain. Three things I’ve found helpful:
1. Remain disciplined & use the docs yourself.
2. Bring your doc on screen in a real-time meeting about the topic & update it with the discussion.
3. Link to the doc in emails instead of replying inline.
That said… I’m researching the balance between wiki-style docs and “generated” docs like javadoc, OpenAPI, etc. I wonder if I’m writing too much in the wiki…
Interview them on parts of the system they know well. Capture what they're saying in a document. Draw diagrams together. Write the doc together, show them how you go through the process.
It will show you value their knowledge, and that writing things down means valuing your own knowledge.
A tip I have is creating tickets for creating documentation and treating them the same as coding tickets.
Writing documentation is always difficult. It takes a lot of understanding to be able to write.
Often times I think people find themselves in a situation where they need to understand something - but they aren't doing so to write documentation - they're doing so because they have to.
So, if you envision achieving this understanding as climbing a mountain - then documentation is the extra hill at the top you don't want to cross. By the time you're done understanding, the last thing you really want to do is write documentation.
Additionally, documentation is sometimes thankless work.
Making a ticket for documentation kinda solves both of these. 1) You can write a bunch of bullet points and have it be very messy within a ticket, and then you can use those bullet points within the ticket to make the documentation. 2) A ticket is a way of recognizing that documentation requires time and effort, and in a ticket form you have to make time for it in your sprint.
Is this a red flag? Kinda. If you have to write tickets for documents it might mean your team isn't appreciating effort towards documentation, you might have to write tickets to make people write documentation, and you team isn't making time for documentation.
On the other hand, it's a great way to get major pieces of documentation done if you have huge holes in your documentation. For example, if you have a document you need to write that will take 4+ hours of work, it might be a good idea to put that into a ticket.
I think maybe I have a different takeaway. The point is to make yourself non-critical. That does not necessarily mean copious amounts of documentation or beautiful diagrams. I don't mean to read too much into your message but there is such a thing as a pedantic documentation. There's a saying in my team: in almost all cases, "short beats precise".
If i were in your shoes, I would ask feedback from my colleagues: am I communicating in a way that works for my teammates? Am I too verbose? Does my doc look intimidating? Are they not interested? What would interest them and could I get to the point faster? Maybe talk about your goals? Maybe your teammates or you manager are not bought in to the idea that people should relinquish their criticality. Maybe they like being like a little sovereign on their chunk of infrastructure, and don't like wasting time learning a system that they see as not theirs, in which case there's a goal alignment problem.
I'm saying this assuming that you can expect competent and helpful feedback. It may or may not be the case, it's up to you to assess. However you sound like you're already in blaming mode, and I would encourage you not to be. Maybe you're not communicating in a way that works for them. Maybe they need to be convinced that it's worth their time in the first place. If you determine that your colleagues are a lost cause because they do not have the interest or skill, don't waste your time trying to craft the perfect comms either.
Beyond documentation it also means paying super close attention to design. The best systems I've seen were designed with the utmost clarity of purpose, about what they were and what they weren't. It was clear what the important things were and how we were measuring towards these goals. From there, the design flows naturally and the code didn't need much documentation.
I've also seen piles of hacks that made up for their shoddy, misguided, over-engineered design by abundant documentation, which was necessarily hard to understand because the design sucked. There was just no salvation possible through eloquence. Crystal clear design is something that is a lot easier to communicate and share ownership of.
Documenting everything they do is a requisite for everyone on my team. Doing it "beautiful" is not. You can do it just drawing in paper, scanning it and linking the document, fast, almost inmidiatly.
That is very important. You confuse something that is basic with something that is an accessory. Document how software works is essential, writing beautiful diagrams is not. Diagrams must be drawn, just like a teacher does on a blackboard, but they don't need to be perfect.
If you demand beautiful diagrams you require designers with art skills or spending too much time on diagrams software or learning the diagrams' domain specific language.
Either way, spending too much time drawing something could be very bad idea.
If something is important you should demand it on your team, but it is a good idea that you have documented those reasons too and for people on your team to contribute too. You will be surprised how easy is for people to accept them when there are real reasons behind and it is not about another tyrant imposing his will on them with whimsical arbitrariness of autocracy.
But you need to do work too, you must be open to the possibility that it is you who is mistaken, putting your ego (or someone else's ego) to the side. Usually there is very dominant people on the team that constantly fight for dominance, being them right or not.
Do you literally read it aloud? How do they react to that? Are they embarrassed they didn't read it? Do they notice they could have gotten the information from the documents? Have you ever pushed back on a meeting request?
But that's about how to push them. Have you asked them if the documents are hard to read? What are their length - are they overly long? Have you done any testing to see if they even open and struggle with the documentation before they call you?
I don't literally read aloud the document but I do end up going through and paraphrasing what each section says. I don't think people are generally embarrassed they haven't read up in advance, they'll show up like "okay so what is this all about?".
I do include 'Summary' paragraphs at the top that provide a TL;DR for an entire 1-ish page doc. I think people will usually open the doc for a few seconds maybe and then brush it off because the general team culture is that all important information will be passed verbally anyways so no point reading now.
Actually I guess I would like to encourage the entire team to do a bit more of this practice of writing things down. For instance, tickets are usually just ~3 word titles with no context or specifics. It's only once the team meets and verbally describes what the tickets mean, that the work can actually be done. I've noticed this sort of culture at multiple companies now actually.
A big part of how to move forward would depend on your position within your company. Are your peers not reading it? People junior to you? People senior to you? Does your boss appreciate your documenting habits or hate that you waste company time?
As for the tickets, is it a problem that work isn't don't on them before the meeting?
In our team, nobody talks and it sux too. Because in writing they dont explain context. Plus they write very terse documents, because writing well takes too much effort.
I have personally done it to fend on a project manager or two or to make sure that I don't misunderstand anything with a deadline someone is hounding me for.
For some reason "I am meeting with X to address it" sounds better than "I am reading Y to address it." Not sure why. Just something I have noticed.
So in my case it is office politics.
Reading documentation/writing documentation is not considered quite as productive work.
Just reply, "this is covered in the documentation." If they say, "I can't find where," find the broad section it's in and send them that. Then, the subsection. Then the page. Gradually get more and more specific instead of agreeing to a meeting, but try and drag that back-and-forth out as long as possible. Don't explain the docs at any point, only send them the location of the thing you want them to read. If they say they don't understand, don't explain or agree to meet. Just get more specific. Reply slowly.
If they still push for a meeting after that, schedule it so far into the future that it becomes more painful for them to wait than to put effort into understanding the docs. Make this a pattern.
If that doesn't work, get Machiavellian. Schedule the meetings, but occasionally cancel those meetings (and only those meetings) on short-notice. Don't let meetings give them confidence that they will get an easy explanation by X date - make them price in a lack of reliability. Use the same strategy businesses use - make processes you want people to avoid using, unpleasant to deal with. Maybe make it clear that you see those meetings as uniquely low-priority, so the flakiness is bounded.
They're doing it because it's easy to offload the responsibility onto you. It's easier to have you spoon-feed them than to pull their pants up. So you have to make it difficult, so it becomes easier for them to pull their pants up.
Obviously, only use this strategy with co-workers, never with people above you. And if the docs don't answer the question, be extremely reliable and make it explicit in your response: "this isn't covered in the docs, so answering this is high-priority. The foo works by barring the snee..."
I guess it’s hard to say, there could be a number of options, depending on the reasons of your coworkers. Maybe your docs aren’t useful to them? E.g. they might see the docs as too basic, too advanced, unintuitive, or too hard to maintain. Or perhaps they prefer to be indispensable to e.g. ensure job stability?
It doesn't solve everything, but when people ask you questions that are answered in documentation, answer those questions with a link to that documentation. Some people will always go straight to you, but over time, others will learn to check documentation first and a smaller subset of those will see the value in that and start following that approach themselves.
Almost everyone understands the value of DRY in code, but not everyone sees the value of it in day to day processes in the same light.
Rule 0 of software is this: People. Will. Not. Read. Anything.
Error messages? Nope. Popup boxes? Nope. Documentation? Nope. Emails? Nope. Jira descriptions and reproduction steps? Nope. Example code? Nope.
One person out of a hundred will bother to read anything. Ninety nine will click through or hurriedly scan, and then steal your time to answer questions answered in the first sentence. Or to make you Google things for them.
People will read, but only up until it gets too much or abusive of their attention. Error messages can be cryptic and cause some mental trashing until the reader realized her bad investment of attention, gives up, and makes a mental note to self to lower the expected value of error messages in the future. Emails? Not when you get overburden with the amount received and when a lot of those have a very tenuous relation with you (but if a future demand pops up for a knowledgeable person, you're in the recipient list, so you're considered ready and waiting). Documentation? Alas, there's only so much of it that can be really useful for a reader and only so much quality grooming that the confluence of various budgets (writer's patience and attention being the most important ones) could support. One reason people prefer to ask directly is because this way they get a chance to control the interaction and direct the answers to whatever they really need and thus avoid waste.
This being said, I am one of those technical guy having to answer to a lot of (seemingly lazy) people, which is something that often drives me crazy. The trick I come up with is to show my genuine impatience, redirect new people to the ones I've already explained the same thing, and let them milk each other for information.
You have the right to refuse a meeting or to step away from it if you feel like it will be unproductive because of other people's laziness.
Tangentially related, if someone asks a question, refer them to the documentation - finding the right docs can be harder than reading them. Teach a man to fish etc.
If the average technical document was useful and clear, I think more people would be inclined to read whatever you're handing out.
It may be that your coworkers are so used to the piss-poor quality of average documentation that they don't bother-- even if yours is high quality. I can't blame them.
Most documentation I've seen is some combination of:
- Inaccurate
- Verbose
- Poorly organized
When I'm handed a 20 page document consisting mostly of lengthy paragraphs, I generally opt out and just go look at the code.
I'm much more likely to read further if a document leads with:
- A single-sentence summary
- A 5(ish) bullet overview
- Prerequisite knowledge
It signals that I'm in for a better-than-average read.
Incidentally, the Google course[0] or the equivalent is excellent.
To most people stuff is irrelevant until they actually get the time to work on it, have to collaborate and have access to it. In most cases 3/3 aren't present, and is why pair programming was discovered.
I hear your frustration. I hope you can find resolution, and that your team will eventually see the value, or that you can find a culture that values what you are doing.
You might be making yourself disposable specifically in the context of your original role which you are basically making redundant by documenting and automating everything - but trust me any sensible business will want to keep a staff member who massively improved their team's productivity (by enabling them to be more independent with less silo'd knowledge) and reduced the business' risk exposure (by making potentially critical knowledge more accessible and reducing single points of failure).
Employees who try to become indesposable by turning themselves into a mega-silo of knowledge that nobody else in the org has might gain some job security in the short term but they lose out on any potential job progression.
Turning yourself into a silo like this is practically blackmailing your employer into keeping you. They might keep you employed because they need to keep their systems online, but they will also not think twice about replacing you as soon as an opportunity is presented. That is making yourself disposable.
Turning yourself into a leader who improves the outcomes of various teams in a business will not only make you indespensable, it's genuinely the best (if not the only realistic) path for an engineer to work their way up into more senior or C-suite positions.
>trust me any sensible business will want to keep a staff member who massively improved their team's productivity
Whether sensible or not a lot of companies do not do this.
It is difficult to measure productivity increases at the best of times. Increasing your teams productivity doubly so. Increasing their productivity may even be net negative for you as it makes them look more effective compared to you.
This may be counterproductive for the company in question and seem idiotic but that doesn't stop it from being common. It's common precisely because it's a template for how most workers are treated. If you see programmers as individual resources not markedly different to Uber drivers (and SO many do) this way of thinking is completely natural.
>Turning yourself into a silo like this is practically blackmailing your employer into keeping you. They might keep you employed because they need to keep their systems online, but they will also not think twice about replacing you as soon as an opportunity is presented.
Right. But how else do you deal with a company that demonstrates repeatedly that they wouldn't think twice about replacing you no matter what? Starting from that assumption along with the restriction that you cannot easily hop jobs - what else are you supposed to do?
Plenty of tech is egalitarian and productive and not like this, but a larger unfashionable un-talked about underbelly of the industry most certainly is. The bimodal salary distribution also comes attached to bimodal working conditions.
> Turning yourself into a silo like this is practically blackmailing your employer into keeping you. They might keep you employed because they need to keep their systems online, but they will also not think twice about replacing you as soon as an opportunity is presented.
All employer / employee relationships have this dynamic. I get paid _n_ because my employer cannot figure out an effective way to do it cheaper, but as soon as they can I will no longer be paid _n_. While I think blackmail isn't an accurate description of this, what you're describing exists in all employment situations. Making yourself more disposable is only going to give the employer more power, which might work out better or worse depending on the employer.
> All employer / employee relationships have this dynamic
Wrong, no employer relies on a newly hired employee the way they rely on a senior knowledge silo'd engineer with a decade+ of domain knowledge which they are reluctant to share. In most jobs the employee is not in a position to have that kind of bargaining leverage. That leverage is only gained by an employee either intentionally and maliciously making the codebase as esoteric and unmaintainable as possible, or poor management not planning for these risks sufficiently e.g. not hiring more staff for a legacy COBOL system team as it's members leave until there's only one guy left who understands it.
> While I think blackmail isn't an accurate description of this
I'd argue it is. You know their business depends on you as a result of you actively working to make it depend on you, you use that knowledge to leverage your position in bargaining for higher pay or to never get fired from a low-effort "cruiser" job. Essentially blackmailing the business into continuing your employment under threat of losses caused by you leaving and nobody else being able to maintain the mess you created. This is not a normal employer / employee relationship dynamic at all.
People that play zero sum games only get to play with other zero sum players. There is some risk they will lose. People that play win-win games get to play with other winners (and be winners).
I hate to break it to you, but every economic scenario is a zero-sum game. In order for an economy to work you have to have a relatively fixed amount of resources.
This whole win-win ideology is mostly a tool to erase where the losers are, and to make losers feel better about losing. Every increase in my paycheck is a decrease in someone else's.
If that was even remotely true, we would still be sitting in caves sharing raw animal scraps. Fortunately it's not true, and things like discovering fire and inventing tools don't take resources away from others, but instead increase resources for everyone. This is just as true in the modern economy.
Obviously the inventor of fire got more of a reward from his invention's bounty, but everyone still benefited. Similarly whoever automates your job gets most of the reward, but ideally we all benefit through cheaper products.
At least, that's how it's supposed to work. Obviously it doesn't always.
I had a pretty strong visceral reaction to this article.
prob because i just read about the 1%ers avoiding paying taxes, and a thousand other much-more-horrific things, only to see the top post on HN advocating for workers to make themselves even more dispensable that they/we already are -- and i don't think it was meant as a joke. :-D
i've always done the 'obsolete yourself' routine, and still do/am -- part of it was/is always self-interest (not advancement, but getting freed from having to do stupid shit), but part of it was/is 'just doing the right thing by the company' and thereby hopefully being part of a successful operation which, if you're not doing anything too evil, would allow me to take some pride in it.
but i know that many of my improvements to products/documentation/training/etc. only help offshore myself _and_ all my co-workers, especially those of us in the US and other expensive places (and we don't even get health insurance).
if i was part of some type of co-op, all that would be taken care of.
You are disposable though, everyone is. It's generally a losing game to try to cement your position by playing gatekeeper on institutional knowledge, because at best it will prevent you from ever being promoted, and at worst will peg you as a single-point-of-failure liability that needs to be dealt with proactively. I understand this sort of defensive posture might make sense in some companies/situations, but the article is clearly talking about software engineers in large upwardly mobile companies. In those situations it's essential to have a non-adversarial and trusting relationship with your boss, if you don't trust your boss than that's the first thing to address by any means necessary.
I was on a team of 2 and underpaid for my YOE. My boss gave me the standard speech about the company not having the money to increase my comp, and said the company wouldn't be able to counteroffer anything I interviewed for.
I was doing interview prep and my coworker gave notice. I told my boss the range I was interviewing for, and got a comp adjustment the next day. It was a 60% raise.
If I were you I would have left that place even with the raise, or stuck around just long enough for me to get another opportunity. Clearly they don't value you unless you force they hand. Why stick around for that?
My approach to interviewing was basically reject any companies paying under X, and slowly increase X over time as I got practice interviewing with the easier companies. I was only interviewing with one company that could pay X, and they didn't end up giving me the offer.
I like my coworkers and the work I'm doing, but mainly my current company came in with the highest offer.
And to the comments saying the employer could "replace you any time" - most cases, they just don't know how to do so, or have the time and money to do so.
This strange article teaches you to do your employer's job by making it easier to replace you.
Exactly this. If you are a single point of failure knowledge silo, the business sees you as a liability since if you decide to quit, their business is then screwed. This is why turning yourself into a silo is making yourself disposable - it gives the employer a very good reason to try and find an alternative to continuing their reliance on you.
Not "if you follow all these rules religiously, you will even guarantee yourself a lifetime of employment, since no one but you has a hope in hell of maintaining the code."
I don't think OP is advocating making yourself SoP. I think what OP is saying, is that you should not waste your precious mental effort or free time to unmake yourself as SoP for the company, unless you're tasked to do so and paid for it. I.e. if it's in your job description that you'll be documenting all the things, then you'll do it, on paid time.
Is your goal to be indispensable as in the only person still able to maintain some ancient legacy project that is still continuing? Or as in the person who gets things done?
Highly-paid professions have cookie-cutter skill-sets taught from the same textbooks at professional schools with the same basic curricula. They are valuable because those skills are valued, not because they trap their clients in some kind of infinite treatment plan.
My goal is to be the latter but I've worked with plenty of people who made it a goal to be the former.
I don't think it's necessarily irrational.
If you're self aware enough to know that you're on the wrong side of the programmer bell curve, you're counting down the days until retirement, if you're living in a market with relatively few tech jobs - this makes sense.
From detailed experience on this you want to be both the first person to be asked to take on a complex problem and the last person out of the door when things get tough.
Make yourself indispensable through being the person running towards danger, being helpful to your colleagues, being knowledgable and treating people with respect but only write stuff down when asked lest someone think you're replaceable by a few confluence pages.
Sounds like you're writing from the perspective of an employee. The advice is a lot more applicable if you read it from the perspective of a founder — one who might want to get off the rocketship they've built at some point, without causing it to blow up (and tanking the value of their equity.)
> War is peace. Freedom is slavery. Ignorance is strength.
With all due respect, it's overdramatic and ridiculous to quote Orwell. Comparing a blog post about career advice to totalitarian state propaganda is absurd.
Any good team worth their salt will recognize that those with siloed information on the team are a threat to productivity to everyone else. People should get hired and kept based on their ability to learn, their approach to problem-solving, and their ability to share knowledge and unshackle their coworkers from any dependencies on oneself. If a coworker in my organization had disproportionate value stemming from a cache of undocumented information (meaning that then writing documentation would make them disposable), then they’re not worth having in the long run.
A smart manager would start finding someone to receive that knowledge and the smart employee would volunteer to learn. Giving raises to the person with the siloed information to incentivize them to work and share information with other employees is a relatively inexpensive cost to the alternative of spending a yearly salary on someone who’s main draw is being a walking notion/confluence page
Yea, when the person who is disposable quits, she gets a farewell lunch at best. When a person who is determined to be indispensable quits he gets a counteroffer.
Yeah I document stuff when I'm assigned it (say it has users that aren't programmers), or I have to take notes that I will understand. I don't dumb it down so a "newb" can take over my place, I document enough so that 6 months or more down the road I can come back to it and have a reasonable review of what's going on.
The truth is, your disposability has nothing to do with how well you do your job, and everything to do with how visible you are. By writing documentation you're making sure that your name is attached to everything in a huge area that most people ignore.
True to the title and not the article, I actually went through this phase recently. I was interviewing for a new job that I was excited about getting. I purposefully never got my hopes up, but towards the end I knew I was going to get the job.
I went into 2 weeks notice mode. I started getting stuff done that I put off doing. I finished stuff that were on my list of to-dos for years. I was extremely productive. Felt amazing, and that feeling has continued on and I’ve continued to be more productive than I ever have. I got out of my rut.
Force yourself into the mindset that you only have 30 days left to get things done. It may work wonders for your productivity.
I'm similarly in a bit of a rut; my codebase is in decent shape, my backlog could use a lot of work but eh, and there's enough work and job security at my current job to last me years if I want to.
I mean I don't, and I won't see this product be finished unless we suddenly get a lot more people to work on, but still.
A couple of months ago I did a similar thing by making a "Before COVID is over" todo list of projects I wanted to complete and goals I wanted to accomplish before some kind of "normal" life came back. I got an insane amount of things done. I'm finishing the last item on that todo list today.
The first few months of covid for me was getting the massive backlog of things I needed to do done at home. It was fantastic to feel like I actually had a balance in my work and home life for once.
Hmmm, I have mixed views on almost all these points, context matters. Much of these views seem to stem from a career working in large orgs, not resource constrained startups
1. Document your knowledge? Well document the right knowledge, endless documents with all the pro's / cons of every choice noted will loose the signal in all the noise.
2. Document your long-term plans? In IT long terms plans means the next 3 - 6 months. Maybe document your thoughts on where something should go, but make it brief.
3. Document your meetings? Well document meetings outcomes / actions and only very important discussion points - no one will care in a couple of weeks
4. Bring others to meetings? Maybe, only if it really adds value (for context or for education) otherwise your burning valuable time
5. Train people around you? Agreed, at appropriate times
6. Identify and train your replacement? Not sure that is all that useful unless you're actually moving on.
7. Give power to the people? If what was meant was enabling broader inclusive decision making - agreed. But otherwise, fully autonomous operating modes need to earn that trust.
8. Do not make yourself the point of contact? Depends, if you're a manager or the decision maker, you need to be the point of contact.
9. Delegate? yes, to a point see 7
10. Always be learning? Yes, of course. But not at the expense of the greater goals (personal / project / company). Nothing worse than an engineer that has not delivered because 'they were learning / wanted to try a new framework.
I feel like all of your points add unnecessary clarity. I don't think anyone would assume you should document the wrong things, or plan what you can't plan, or train people at inappropriate times.
The only one I flat out disagree with is your clarification on #6. I do think it is useful to find an "apprentice" or "successor" that can take your role on; this is useful for a few reasons: 1) it allows you to move on (either via promotion or leaving the company) and 2) it gives you a support system (want to take a vacation? now you can!)
Where I work there is an entire documentation department, that is almost entirely focused on their templates/standardized documents & proceess, than are are the actual content.
Yeah, no. I've literally read hundreds of RFCs, thousands of man pages, and who knows how much else. If I spent time writing down everything I know, I'd never get anything else done. And it's not like I'm some supergenius, all of this info is available freely on the internet. But that doesn't stop folks from asking about DNS, TCP, and other well documented things.
Many times domain knowledge is just a person who has the answers somewhat fresh in memory so you don't have to go trudging. But writing those things down each time is both futile and redundant.
RFC's and man pages are written down already. When they say "write things down" it's not about duplicating that effort, though you might make an FAQ that links to them.
Point 1 specifically says to write things down every time someone asks you a question. Taking DNS as an example, 1034 1035/4034 4035, among some others, I don't see how that's helpful even if I make a linking FAQ. My notes would say 'DNS question, read these 4 RFCs' over and over and over.
This is so bizarre, what questions are you getting that require you to refer to the rfc - something with such detail that it covers things like how many bytes are allocated to which field.
If you're doing something so niche like some kind of network analysis tool, then your colleagues should already have the rfcs as a very basic reference.
Otherwise, if someone is asking very practical questions like, how to add a cname or something, then rfcs are way too theoretical.
If people trip up with certain things all the time, then is the technology itself suited for the problems that people need to solve?
Because at that point, it feels like people are serving the technology and its many quirks, not the other way around.
But regardless of that thought, i think both your words and those of the parent comment have merit - different levels of detail fit into different pieces of text (RFCs, vs a "How To" blog post), which fit different purposes. The quality of the information in either, however, still remains in question (given that some popular implementations of technologies, don't always even respect RFCs fully).
The article is not a bible and there is something called judgement. If you are getting asked DNS questions all the time, this may be indicator of a wider knowledge issue and may be you can suggest conducting an internal session on DNS. Apply common sense.
I think you’re interpreting the advice way too literally. The author probably didn’t mean for you to document the answer to every single question you get, but questions you get about the system or domain you’re working, and where the answer isn’t readily available anywhere else.
I don't disagree with you. If the question was about design decisions I'd made, I'd be in full agreement. But the article quite literally says 'every time.' You could rightly say I'm being pedantic, but if you're going to write life advice, it should be quite specific IMO. I'm not trying to be a jerk, but rightly (also IMO) pointing out flaws with the wording and tone.
> Every time someone asks you a question, they are highlighting a gap in the documentation.
This is a sensible statement assuming that the question is about the domain or system you’re an expert in. Not “what time is it” or anything like that.
> Take the chance to write the answer down
Perhaps the author should have qualified this advise with “take the chance to consider”, but I think the advise stands well on its own and I understand to apply common sense to it.
You could document what common issues you have or any tricky situation you dealt with. You don’t need to say “dns stands for domain na…” but knowing the why behind some of your decisions is super useful.
Yep, my indespensibleness is that I have all this mostly useness knowledge in my head, and if you show me the problem, I can usually get something useful out of my brain to get somewhere quickly. And if not, I can skim the code and get an idea; and if not, I can sort of operate a debugger.
What do you want me to write down to help someone else do that? Read all the things, just in case!
I think the article is not about general technical knowledge or even knowledge about specific technology used at your company but more about e.g. why a certain way to model your domain makes sense or how an unusual system design will pay off because of future plan X discussed with group of people Y in meeting Z - and here is the architecture diagram for it.
> Yeah, no. I've literally read hundreds of RFCs, thousands of man pages
Well, that didn't take more than a single line: "please remember to check relevant RFCs and man pages for additional information. This system depends on DNS for round robin load balancing (etc)" :)
But it also says .."in a document, bug, code comment—wherever..."
You don't have to make a big effort of it. Paste the question and answers from the emails into a text file. Make it into a FAQ email to share or paste it into a comment block the next time you mess with that code.
"Document your meetings" - ugh I'm still surprised 20 years into my career at the amount of times people hold a meeting and DON'T TAKE ANY MINUTES!!! I recently asked someone, "Do you not normally take minutes?" His response, "I just generally keep it in my head." I thought, "What about the other 10 people on this call? You (foolishly) assume they have the same photographic recall? I certainly don't!"
People - document your meetings! It takes a few minutes. And it will save your ass down the line when some inevitable squabble arises over what people "agreed to work on" but there is no paper trail to settle the argument!
It would be a worthwhile investment to pay an administrative assistant (or, actually, stenographer) solely to sit in on meetings and take notes.
One would think that this ought to be automatic these days, since we've got speech-to-text that mostly works, and ubiquitous meeting recording, and yet...
When I attend meetings I take notes. I'm willing to share those notes with anyone who needs them. I look back at my notes to recall details or find key links and figures.
This makes me a significantly better engineer and subject matter expert.
I'd agree on most points, but like others, 1 & 2 I don't agree with.
Most of my knowledge is useless or irrelevant, so taking the time to document this knowledge is a waste of time. 90% of writing a document is understanding your audience and "document your knowledge" misses that point. Littering documents and code with various tidbits is also not very helpful and probably not worth anyone's time.
Documenting long term plans is also pretty useless. Realistically, anything past 30 days is not going to happen. Documenting your strategy and decision making process may be useful, but your idealistic plans? Probably not unless it's just a few bullet points.
The most important documentation is usually the "why?", which ideally should be written before the project starts. Documentation outside of the scope of in-flight projects (which 1 & 2 seem to be encouraging) are not as important as they can be discovered with a tiny bit of effort.
Exactly and document rot is a real thing. No amount of wikis, knowledge bases, notes what have you will never be enough to capture the info updates. We live in an agile world after all. Maintaining documentation/institutional knowledge is a sisyphean task.
Honestly, this blog post is incredibly, incredibly bad advice (well intentioned) but still really bad. The average organisation doesn't operate this way.
If you make yourself disposable you are far far more likely to be disposed of then promoted in 9 out of 10 companies.
I would even go as far and as cynical to say that if the documentation you create is so good you will just be replaced with by cheaper staff, outsourced or freelancers/contractors.
edit: honestly, the worst advice i have ever read on HN in like 10 years. you relationship with your employer is based on leverage, if you make yourself too disposable you are skewing the balance of power against yourself.
fwiw i am always a happy to provide basic docs and support to team members but i'm not going to document or automate myself out of a job. i've seen it happen too many times.
Honest question: do you think that the point of view "your relationship with your employer is based on leverage" creates a plethora of twisted incentives that make life for everyone more miserable (while protecting employment, to an extent)
It really does make life miserable in a low key way. Of course it depends a lot on the organisation and the personalities that you work with, particularly management but I would say for every 1 great manager who notices and appreciates your contributions there are 9 who don't.
I have a very cynical perspective of workplace dynamics because I've been (and seen others) burnt too many times for taking the initiative or being (in my opinion) too naive in their relationship with management and HR.
edit: I think i was a bit too harsh my original comment. I think it is good to make yourself disposable (to yourself) but not to the company. If that makes sense. I have lots of documentation and cmd scripts for basic automation but I avoid sharing them on internal wikis or repos. I only share them with devs on request informally.
If you get disposed of in 9 out of 10 companies, then 50% of the time it takes about five disposals to find a job where you do get promoted. Seems like the strategy to take if you want long term success and not long term marginal subsistence.
I do agree - If there are two employees with the same work output, the one who took the time and effort to pave his way to replacement is going to be let go first.
this legitimately makes me feel sad for you. i know that there are companies like this, but do you really want to work for them? i like this article and i feel like taking these initiatives would be greatly valued by my org and would lead to more respect, more responsibility, more visibility, and more pay.
I feel like the fact that there's a lot of dissent in this thread about whether the advice in the article is good or not means that it may be valuable advice. Like, a lot of advice is great, but also obvious, and, therefore, in a sense, is widely understood and known to be true, hence not quite as valuable as some rare advice out there. The kind of advice out there that people may not quite agree on or even understand. The advice in this article may be the second type, judging by the lack of agreement here within the thread.
I died reading your comment, haha thanks. And yeah, you're right, that could literally apply to every controversial article on HN. No disagreements here either.
In my experience the answer is that it depends heavily on your situation. For every one of these bullets, there is a time and place to do that thing and a time not to. What sets senior folks apart is the judgement of when these things would apply and how to do them effectively. If a junior IC comes in and starts cargo culting off this they could easily spend all their time writing useless docs and sowing confusion and disrupting the team while completely ignoring the core competencies of their job.
So it's not that I think the advice is bad, but rather that most individuals would fall into one of two buckets: either they would already intuitively be applying these ideas appropriately, or else they would be unqualified to actually do so.
It might be great advice that people don't understand, but it might also be terrible advice that people do understand. The opinions of a bunch of strangers who you have no trust in isn't enough to inform you either way, but you should note that ought to include both HN readers posting here and the author of the article.
It also undermines your leverage if you want to bargain with the company over things like a raise in salary. You also have less protection against malicious actions from your work.
Personally, I don’t worry about being replaced. It can happen, but I don’t believe it’s helpful to be stressed about it. The way I prepare for it is to try to learn new stuff all the time and keeping in touch with people in the same field.
Which means you need to find a new employer. There are companies and/or managers out there that don’t have these misalign incentives, encourage best practices (like those in this blog post), and provide psychological safety. They exist.
Exactly. If you increase team productivity and your boss fires you for it instead of promoting you, then the company is doomed so why would you want to work for them?
Quite often the high cost of firing someone is exactly the reason why the company wants to fire them. If you're someone who doesn't do things the way the company would like that isn't leverage; that's a reason to push you out.
Years ago I had an employee who had been with me for over a year and hadn't taken any vacation. I encouraged him to plan a vacation sometime in the coming months, in part, because wend don't really know what things he did at work that weren't fully documented and cross-trained on. Got other people cross trained, things documented, and his vacation went smoothly.
A few months later, he got offered a dream job offer, and the transition went smoothly.
I agree. Share everything, and be willing to train up more junior people so they can do your job. I have a (good or bad habit, depending on point of view) of not staying long at jobs, but often returning (I have worked for two managers, three different times; and a couple managers two times). I try not to burn bridges, but I enjoy working on new stuff with new people.
Not related to the article, but I feel like as active engineers we own it to ourselves to always be preparing for the next play. I recently started doing more interview prep even though I'm not unsatisfied with my position. And I even took a few phone screens just for entertaining the idea and testing the water.
Gotta say it just feels nice to be able to go through a couple of those smoothly. I think that actually relieved some latent stress I've been having all this time and made me more at east even at work. Feels good to know that I'm ready when the time comes, even if not now.
A friend of mine does something like this to test the waters. This approach seems to help prepare to be prepared. But then he sometimes has to face the dilemma- whether to accept the next opportunity. :-)
I can't imagine doing this without actively thinking about leaving my current job for whatever company I'm interviewing with.
Which is maybe not a bad idea, say once or twice a year? Even a loyal and supportive manager has certainly run the numbers on life with or without you on the team, and will be told to do so again at some point.
Anything comes to mind i find interesting, especially tech things. I try for knowing their stack and internals and methodology well by the time i,m leaving.
We had an issue stemming from a convoluted setup where images were being copied to a web server every night, from a document server, something went wrong with the logic in the script and we ended up with missing and out dated images on a web site.
I suggested that we just allow the document server to serve the images over http. The response was "We thought about that but decided against it."
I then asked why? Who decided that?
Nobody knew. Had the meeting been documented, we'd hopefully be able to go back and see 'Dave recommended we not do that because of X and Y...'
This is good article though it actually didn’t made any sense in terms of job. There are companies that value good documentation, you will have to write docs to keep your job. And there are companies that don’t care about documentation. By writing documentation, you are wasting your company’s time and money on something that is not important to them. This will not get you promoted but it may get you fired.
You want documentation as a priority, then champion it to your leadership. Show them data that documentation saves cost in long run. But writing docs by yourself is not a good strategy for long term success of your career.
This brings me to my second point, I agree with author if you replace quitting job with dying.
What if a doctor tells you that you have two weeks to live. Will you go do all the things that you always dreamt about or would you be talking with lawyers to get your will and estate in order. Do you have enough life insurance? Are you saving for your family and kids?
If you have taken care of your affairs, now if doctor tells you that you got two weeks left, are you going to rush to work and finish your project or just quit? Are you going to spend next 2 weeks with your kids or go on a long hike? Or something else? Do you do any of that right now?
Yes I want to live my life as if I am always be dying.
After getting acquired and some people laid off and replaced with lower cost workers; I think the only reason I have a job is because of the complexity of the system and that it was built quickly so documentation was lacking. This is a great article don't get me wrong, but if you get acquired people might see you as a cost vs asset.
I guess it’s a good way of thinking. But it’s too idealistic.
You see: if you do this it’s true that you might be able to make everyone’s life easier and you may advance your career, but (you knew there was a but) you also lose most of the leverage that comes with specialization and having critical knowledge. Yes, it may be harder to switch what you’re working on inside the current workplace, but it also means that passing you on promotions and rewards can lead to a lot of pain if you decide to look outside.
As always, there is a soft spot between being the perfect engineer and 100% disposable because of your impeccable “work ethic” vs just being a nightmare to work with and people not having a choice at all.
we had a principal engineer who thought he was very skilled and held critical knowledge and tried to use it as leverage. turns out, everyone else considered that poisonous behavior.
I don’t know the details as I didn’t work directly with him, but from what I understand he was trying to get a sabbatical to figure out some life stuff, but eventually he had to quit, which was not his desired outcome as he needed the income and didn’t have the time to find another job quickly.
getting a sabbatical is different from a raise/promotion. one signals that you have other things going on/you don’t care anymore, the other seeks to assert that you are contributing a lot and should be rewarded for this
> you also lose most of the leverage that comes with specialization and having critical knowledge
Your value does not disappear when there is redundancy within your company. If it is a valuable skill there will always be a demand for it outside, and now you can also claim that you are also capable of coaching others in that skill. If the skill is not valuable to the outside world and is a niche to your company, I’d say you still want to move on from that skill exactly because it is not transferable to other jobs. What if your company goes bankrupt?
true, but redundancy is hard to build on critical or under-documented parts of the code. It’s also hard to build when the knowledge needed is not something you can just sit down and do a brain-dump in an afternoon (ie you need a lot of context to see the light).
So, you can help people grow and keep your skill polished while you build up job security and hoard critical knowledge. I’m not saying it’s the right thing to do - just saying that I’ve seen it done and it worked for the persons doing it.
Having a codebase that is so convoluted that only you can work on is really not a skill you should risk your career on. It might work for those people you have seen in a short period, but long term they fall behind as they not only not develop generally valuable skills (because they are constantly working on that project), they also lack the skills to write clean collaborative code, which makes them less employable. So they would be in a very bad situation when that code base loses its value. (due to company going bankrupt or the project being shelved) My argument is not against hoarding critical knowledge. I am saying that by doing so you will be the single person responsible for that area, and therefore won’t have a chance to grow and diversify your knowledge base. I can only imagine a scenario when you are working in a hostile environment with really dumb management where that attitude could be rewarding and protect you. But in that scenario I would be looking for a new job and try to quit anyways. You don’t want to base your career goals on a specific position/employer.
this can be a giant waste of time and energy. Half the time the stuff may not be used later. if you are on an already established project, doing this more will help.
sounds like author had someone quit and now he doesn't have the knowledge around the person leaving
Similar idea but not related to work: act like you're going to be moving away from town soon. You'll think of all those parks and attractions in your local area that you always said you'd go to but never took the time for.
It's a good ideology, and I would suggest following it where possible, but I do see certain bad assumptions being made. These are the sort of thing I always try to do, but recently I've wound up on a team with only myself to do all architecture, programming, documentation and story writing. We have 2 QAs a team manager and someone who's in charge of coordinating market activity and sort of doing product management, but despite having multiple projects on my plate, I am the only developer. I can document things just fine, but there is no replacement for me to train. I've honestly been trying to make myself replaceable, but sometimes management just doesn't understand how many people they should have hired and when people leave it can easily result in that becoming impossible. Under those circumstances people either burn out and lose those habits, or they simply find a new job and leave just to get away from the bad situation. I'm getting pretty close to burnout in my own situation and I'm eyeballing an escape plan before somebody else can end up putting even more work on me.
> Paradoxically, by being disposable, you free yourself. You make it easier for yourself to grow into a higher-level role and you make it easier for yourself to change the projects you work on.
I think the logical think between "grow into a higher-level role" and "being disposable" is very weak if any?
The company will pay big price to promote a highly-valued employee. The task which the employee was working on will be transferred to other member/team in the company, so the promoted employee could work on more important tasks. Some company allows/requires the promoted employee to also monitor the situation to ensure the transaction of task is done correctly during/after the promotion.
On the other hand, from a company's stand point, a quitting employee should never be a big concern even if someone intentionally make themselves "indispensable".
The points in the article that I agreed with:
- "Document your meetings", I always do and call it memo
- "Give power to the people"
- "Do not make yourself the point of contact", I explain what I was doing in the comments of my code
- Not sure why the author put this in, but "Always be learning"
Real world incentives are truly perverse and don't align with the idealized version from this blog post.
In fact, I think this was written by a manager that was burned by a critical person leaving.
In the real world I've seen too many times the jerks, the firefighter types that create fires that only they can extinguish to get recognition and privileges while making everyone's else life miserable.
> Not sure why the author put this in, but "Always be learning"
The point of the article is that by increasing team productivity to reduce your own tasks, you now have the chance to learn new things and grow into new roles as opposed to being stuck with the same responsibilities.
Maybe I'm in the minority or bubble, but I don't know of anyone who has KPIs tied to documenting knowledge in the first place. Business people and product managers rarely care (and why would they!) about anything outside delivering features and fixing bugs. So that's in the KPIs, and KPIs are what sets priorities inside company.
Edit: accidentally pressed a submit button.
> Business people and product managers rarely care (and why would they!) about anything outside delivering features and fixing bugs.
My response to executives and managers with this attitude is that they ought to care about processes beyond delivering product for the same reason that a restaurant owner ought to care about processes beyond cooking meals.
It might sound good to have your chefs do literally nothing but cook all shift, but they also need time to wash dishes, sharpen tools, organize spice racks, track inventory, maintain work stations, mop floors, etc. Neglect these things long enough, and you increase the likelihood of accidents happening and decrease the quality of the meals produced.
Correct. This is why a company that has its shit together will also have engineering managers and engineering leadership generally, in addition to business people and product managers. The engineering leaders, if they are any good, will negotiate and enforce a "you have to give engineers time to rebuild MVPs properly, and to document, etc. etc." policy with business and product.
This made me reflect on a recent experience when I got stuck as a single SW developer maintaining a (more than) mature project. If I had been more friendly and supportive to junior developers and contractors, polished documentation, updated build system, I could probably have left this project much earlier while looking like a better person.
I've lost more coworkers to promotions, transfers and medical emergencies, family problems, mental health breaksz maternity/paternity leave then I ever did to firings and quitting.
Don't be a hero, don't work every day, build redundant systems where you can make an impact but can leave without blowing everything up.
I am not sure. I never found much value in companies internal confluence pages. Mostly outdated and poorly organized.
Long README for project setup is code smell. Things should "just work" with obvious commands. Best code documentation is automated tests.
I think the most important documentation should be your issue tracker. User stories should have clear AC, all work should be captured in tickets and organized in Epics/tags.
My big problem with agile is that the total amount of work done for a particular feature is not captured very well. This makes it hard to make strategic decisions. You might have multiple teams re-inventing the same wheel or facing similar problems.
The question I had reading this: when will my company incentivize this behavior?
I get no significant equity. I just get paid a salary.
As an employee, it’s in my best interest to be indispensable to my company’s operations.
If I have made myself replaceable, I have no leverage over salary negotiations.
Obviously, the argument I’m making here is taking this concept to an extreme. Nonetheless, I think it’s a good question to be asking: why should I do this if my company doesn’t care either way?
The only reason I can think of is that I don’t want to be the point of contact for everything and be bothered off-hours.
But in every other respect, I want my company to think “we couldn’t do it without them” every time my name comes up.
> Document your knowledge. Every time someone asks you a question, they are highlighting a gap in the documentation. Take the chance to write the answer down (in a document, bug, code comment—wherever) so that the next person doesn’t need YOU.
This and many more of his advice are very good for companies but suck for the individual.
I would say not to follow the authors advice because it will make no one reliant on you. It is also incredible time consuming and will only weaken your position.
This article is basically saying not to drive you car so much or else it won't be fresh for the next owner. This is corporate simping.
This is only good advice for the most senior people or anyone who has unquestionable trust from their management/leadership.
Turns out if you're not one of those people, at review time nobody values this behaviour.
It's only "what did you deliver".
So yes, it's important to train, document, and delegate. It's valuable. You should do it.
But if you still have yet to earn trust or a reputation, and you want to actually exceed expectations and be known as the type of performer that gets things done, you have to lean in a little more into delivery and a little less into all the instructions on this page.
So true! I had an experience after which I sort of emotionally divorced from my company (but not the friends I made working there!) and it left me more relaxed, more balsy and with an attitude like “They are lucky they have me, and if they don’t think so? Fine, bye!” I ask less for permission, take ownership more, am less afraid to get fired. And it is very much appreciated!
Moreover, the occasional job interview I go to (because why not) taught me a lot and sometimes almost led to new and valuable collaborations.
Worth reading `Linchpin: Are You Indispensable? ' by Seth Godin
> Seth Godin describes a Linchpin as somebody in an organization who is indispensable - who simply cannot be replaced because their role is just far too unique and valuable.
My comapny reduced the numbers of epmloyees from 1500 to less than 200. As soon as they feel you are replaceable, you are eifher disposed or replaced by a cheaper one overseas.
All great advice. I guess I behave in many of these ways just because of my personality, I've never understood (or liked) people who try to entrench themselves in some position and become irreplaceable, I've never seen how you can think that is a good strategy for yourself, and this article explains some of that.
This one is maybe even too obvious for the article, but: share your passwords. Even if you are the only developer on the team, you should not be the only one with access.
Also I like to think of this methodology as “what if I got amnesia tomorrow?” You need to get everything out of your head onto a shared knowledgebase.
I agree in spirit but would revise: it's a security threat and against some company policies to explicitly share passwords in the clear. The ideal is to add your password to a corporate password vault, some of which can then authenticate for coworkers without them knowing explicitly what it is.
'Every time someone asks you a question, they are highlighting a gap in the documentation.'
This would be ideal, but whenever someone asks me a question there is a high probability that they just don't want to take the time to read and process the documentation.
One thing I’ll say is that not everyone knows how to write good documentation. There’s a difference between writing a reference index, a getting started guide, design pattern motivation, and so on. They are all very different things.
You assume that all devs are responsible, they are not. It's a dangerous mindset "always be quitting" for someone who is not responsible. They will do exactly the opposite of what is mentioned in the article.
I always expressed this as having a plan in place in case I were to get hit by a bus. The world can't come to a halt just because I wake up dead one day. It's very much the same idea, I think.
As a one man shop for the small company I work for this is great advice. Inspired me to create a new "read this in case of emergency" doc if I get hit by a bus.
Perhaps the attitude instead should be: Always Be Interviewing
Everybody's replaceable. Capitalist corporations will replace you at the drop of a hat if they can. The only way to safeguard yourself is to be ready for it.
This is good advice for founders and people intent on, and capable of, advancement, but it's generally bad advice for everyone else because it makes them easily disposable.
I stumble on one DevOps guy who wrote every bloody thing happening in the system. He likes doing it, but from the way people were asking questions in the common chatrooms, group emails, I knew nobody read them. He loves plain text, nicely formatted with the old-school Unix-styles et al. I had talks with him outside of work and found him fascinating; I asked him help with my hobby, home-lab tinkerings, etc.
By that time, I had already started internal blog groups and was encouraging people to write. And indeed, a lot of people came out to write about engineering, marketing, product, and it became a routine for people to show off what they can do, what they love, and what they are good at.
In one of my regular company-wide emailers, I dedicated a big piece to the DevOps guy, pointing to his work and the beauty of his documentations. People loved it, and they began reading it. He remained a friend. That mailer was the only way I could highlight people I encounter doing good work, to the whole team up to the CxOs.
By the time I left the company, I was responsible for many vital things in the company, but I could transition everything smoothly with the documents and credential details (thanks to 1Password).
In the last year or so, I have been thinking more about -- always be dying. I think the similar vein of Always be Quitting; I try to document, write out details, just in case I die and my family has to figure out the intricacies.