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.
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.
Writing skills are even more depressing. 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.
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".
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?
- Why don't I unsubscribe from marketing emails?
- etc.
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.
In short, its really hard to change bad habits.
That's part of why Amazon famously banned PowerPoint.
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.
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.
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.
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...
EDIT: Clearer phrasing
Or maybe they're burnt out, just there for the paycheck, and want to go home (log off) ?
There's a whole spectrum of reasons.
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.
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 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.
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.
The book The Unicorn Project shows how it is dysfunctional. Leaders tend to thrive doing nothing of value in such environments.
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.
>have at best average IQ if not lower.
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.
So if I said there were a lot of homicides in NYC last year, you would think that over 4 million people were killed?
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".
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.
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.
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.
Documentation is the required thing.
Developers should slow down. Knocking out features is not the be all and end all.
If you spend on the clock.time coding, you can spend some of it reading.
Also most people simply cannot write good documentation especially for complex topics.
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.
Many developers are handymen, not engineers.
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.
Using documentation to clarify concepts as I go is certainly aomething that happens, but it is not the reason i do it.
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...
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.
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.
I'm working on https://www.sherdoc.co/ right now to help fix that issue.
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.
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.
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.
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
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.
Your sentiment feels more like "dig a hole, it builds character!"
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.
I only ask because, first and foremost, documentation is for you.
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.
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.
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.
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
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.
[0] What the Fastly outage can teach us about writing error messages https://news.ycombinator.com/item?id=27443519
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.”
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...
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.
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.
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.
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.
Does reading your documents really create value for others, or do you want them to validate and give your "more impact"?
You have to first make people curious about your ideas, or they will simply not care.
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.
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.
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 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.
As for the tickets, is it a problem that work isn't don't on them before the meeting?
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.
Wait, what? I always found reading documentation to be one of the more productive uses of my time.
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..."
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.
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.
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.
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.
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
I'm much more likely to read further if a document leads with:
- A single-sentence summary
- A 5(ish) bullet overview
- Prerequisite knowledge
Incidentally, the Google course[0] or the equivalent is excellent.
The culture is simply set for other priorities.
Once documentation becomes longer than a page or two, most people's brains shut down and go into TL;DR mode.