10 ms·

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 th

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.

koonsolo 5y ago
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.
- Layke1123 5y ago
  Thats not true. Good documentation is INVALUABLE. Deciphering some arcane manuscript that is out of date and can't cover all the nuances of what could go wrong is asking for trouble when teaching people. Teachers exist for a reason. It's because people learn better from people, especially in the middle of a pandemic where we've been forced to be apart.
- vladvasiliu 5y ago
  > 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.
  - random_kris 5y ago
    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
    - vladvasiliu 5y ago
      > 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 https://news.ycombinator.com/item?id=27443519
      - random_kris 5y ago
        I agree on points you gave.
    - dahart 5y ago
- random_kris 5y ago
  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)
  - raffraffraff 5y ago
    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")
- touisteur 5y ago
  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...
bhshhshs 5y ago
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.
- _nalply 5y ago
  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.
  - loopz 5y ago
    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.
- P_I_Staker 5y ago
  > My advice is don’t document 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.
mgarciaisaia 5y ago
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.
- StavrosK 5y ago
  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. I'm working on https://www.sherdoc.co/ https://www.sherdoc.co/ right now to help fix that issue.
AlexCoventry 5y ago
Maybe ask them. Something like "Can you think of any ways I could have made it easier for you to find this documentation independently?"
adreamingsoul 5y ago
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.
wildpeaks 5y ago
At the bare minimum, the documentation will be useful to Future You even if teammates don't use it.
splittingTimes 5y ago
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.
- Cthulhu_ 5y ago
  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.
thih9 5y ago
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?
mjfl 5y ago
Quit?
colordrops 5y ago
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?
- jehlakj 5y ago
  This has been my experience as well. I’ve worked at several companies and this is far more common than I had hoped when I started my career. Also most people simply cannot write good documentation especially for complex topics.
  - atoav 5y ago
    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. Many developers are handymen, not engineers.
    - colordrops 5y ago
      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.
      - marrs 5y ago
        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.
        gregoriol 5y ago
        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.
saarp 5y ago
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.
- junon 5y ago
  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!"
  - popinman322 5y ago
    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.
  - marrs 5y ago
    Has this been your experience with writing documentation or are you just saying this because it’s obvious. I only ask because, first and foremost, documentation is for you.
    - junon 5y ago
      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.
coderdd 5y ago
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.
- rualca 5y ago
  > 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.
  - deleted 5y ago
    [deleted]
  - splittingTimes 5y ago
    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.
  - Quekid5 5y ago
    > 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... EDIT: Clearer phrasing
DetroitThrow 5y ago
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.
musicale 5y ago
Obviously it is much easier for them to have you read the documentation so they don't have to. Once documentation becomes longer than a page or two, most people's brains shut down and go into TL;DR mode.
brundolf 5y ago
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
- hinkley 5y ago
  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.
MattGaiser 5y ago
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.
- HWR_14 5y ago
  > 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.
  - rytis 5y ago
    You, yes. But do your superiors think the same? Usually it goes - "well, read if you must, but better do some real work". Unfortunately.
  - MattGaiser 5y ago
    What you or I think it not relevant. It is what the person who signs my paycheque thinks.
  - deleted 5y ago
    [deleted]
valtism 5y ago
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.
HWR_14 5y ago
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?
- uDontKnowMe 5y ago
  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.
  - watwut 5y ago
    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.
  - HWR_14 5y ago
    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?
abraae 5y ago
Did you put a cute animal on the front, give it a funky title, and embed amusing memes at pagely intervals?
sombremesa 5y ago
Read this: http://thecodelesscode.com/case/169?topic=documentation http://thecodelesscode.com/case/169?topic=documentation
- alexellisuk 5y ago
  This is excellent and reminds me of the style of The Richest Man in Babylon. Is it available in print format?
- dano 5y ago
  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.
ridaj 5y ago
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.
Cthulhu_ 5y ago
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.
bumbada 5y ago
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.
choeger 5y ago
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.
- eru 5y ago
  Add in the use of PowerPoint to make everything worse. That's part of why Amazon famously banned PowerPoint.
- ianai 5y ago
  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.
- Tainnor 5y ago
  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.
johbjo 5y ago
Far fetched analogy; a woman laughs at your jokes to acknowledge that flirting is welcome, not as an involuntary response to your brilliant humour. 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.
mch82 5y ago
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…
loopz 5y ago
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. The culture is simply set for other priorities.
galoisgirl 5y ago
Is not reading it the only thing where they don't do their part of the job?
christophilus 5y ago
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. [0] https://developers.google.com/tech-writing https://developers.google.com/tech-writing
bostonsre 5y ago
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.
cyrialize 5y ago
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.
MillenialMan 5y ago
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..."
spion 5y ago
Pick their brain. 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.
- spion 5y ago
  (This should be with a reason e.g. if you're working on a part that you don't know too well, trying to learn how it works)
thrower123 5y ago
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.
- restalis 5y ago
  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.
mbrodersen 5y ago
People do what gets rewarded. People stop doing what gets punished.

koonsolo 5y ago

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.

Layke1123 5y ago
Thats not true. Good documentation is INVALUABLE. Deciphering some arcane manuscript that is out of date and can't cover all the nuances of what could go wrong is asking for trouble when teaching people. Teachers exist for a reason. It's because people learn better from people, especially in the middle of a pandemic where we've been forced to be apart.
vladvasiliu 5y ago
> 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.
- random_kris 5y ago
  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
  - vladvasiliu 5y ago
    > 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 https://news.ycombinator.com/item?id=27443519
    - random_kris 5y ago
      I agree on points you gave.
  - dahart 5y ago
random_kris 5y ago
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)
- raffraffraff 5y ago
  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")
touisteur 5y ago
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...

bhshhshs 5y ago

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.

_nalply 5y ago
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.
- loopz 5y ago
  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.
P_I_Staker 5y ago
> My advice is don’t document 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.

mgarciaisaia 5y ago

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.

StavrosK 5y ago
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. I'm working on https://www.sherdoc.co/ https://www.sherdoc.co/ right now to help fix that issue.

AlexCoventry 5y ago

Maybe ask them. Something like "Can you think of any ways I could have made it easier for you to find this documentation independently?"

adreamingsoul 5y ago

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.

wildpeaks 5y ago

At the bare minimum, the documentation will be useful to Future You even if teammates don't use it.

splittingTimes 5y ago

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.

Cthulhu_ 5y ago
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.

thih9 5y ago

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?

mjfl 5y ago

Quit?

colordrops 5y ago

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?

jehlakj 5y ago
This has been my experience as well. I’ve worked at several companies and this is far more common than I had hoped when I started my career. Also most people simply cannot write good documentation especially for complex topics.
- atoav 5y ago
  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. Many developers are handymen, not engineers.
  - colordrops 5y ago
    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.
    - marrs 5y ago
      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.
      - gregoriol 5y ago
        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.

saarp 5y ago

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.

junon 5y ago
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!"
- popinman322 5y ago
  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.
- marrs 5y ago
  Has this been your experience with writing documentation or are you just saying this because it’s obvious. I only ask because, first and foremost, documentation is for you.
  - junon 5y ago
    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.

coderdd 5y ago

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.

rualca 5y ago
> 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.
- deleted 5y ago
  [deleted]
- splittingTimes 5y ago
  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.
- Quekid5 5y ago
  > 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... EDIT: Clearer phrasing

DetroitThrow 5y ago

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.

musicale 5y ago

Obviously it is much easier for them to have you read the documentation so they don't have to. Once documentation becomes longer than a page or two, most people's brains shut down and go into TL;DR mode.

brundolf 5y ago

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

hinkley 5y ago
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.

MattGaiser 5y ago

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.

HWR_14 5y ago
> 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.
- rytis 5y ago
  You, yes. But do your superiors think the same? Usually it goes - "well, read if you must, but better do some real work". Unfortunately.
- MattGaiser 5y ago
  What you or I think it not relevant. It is what the person who signs my paycheque thinks.
- deleted 5y ago
  [deleted]

valtism 5y ago

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.

HWR_14 5y ago

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?

uDontKnowMe 5y ago
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.
- watwut 5y ago
  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.
- HWR_14 5y ago
  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?

abraae 5y ago

Did you put a cute animal on the front, give it a funky title, and embed amusing memes at pagely intervals?

sombremesa 5y ago

Read this: http://thecodelesscode.com/case/169?topic=documentation http://thecodelesscode.com/case/169?topic=documentation

alexellisuk 5y ago
This is excellent and reminds me of the style of The Richest Man in Babylon. Is it available in print format?
dano 5y ago
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.

ridaj 5y ago

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.

Cthulhu_ 5y ago

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.

bumbada 5y ago

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.

choeger 5y ago

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.

eru 5y ago
Add in the use of PowerPoint to make everything worse. That's part of why Amazon famously banned PowerPoint.
ianai 5y ago
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.
Tainnor 5y ago
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.

johbjo 5y ago

Far fetched analogy; a woman laughs at your jokes to acknowledge that flirting is welcome, not as an involuntary response to your brilliant humour. 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.

mch82 5y ago

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…

loopz 5y ago

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. The culture is simply set for other priorities.

galoisgirl 5y ago

Is not reading it the only thing where they don't do their part of the job?

christophilus 5y ago

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. [0] https://developers.google.com/tech-writing https://developers.google.com/tech-writing

bostonsre 5y ago

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.

cyrialize 5y ago

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.

MillenialMan 5y ago

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..."

spion 5y ago

Pick their brain. 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.

spion 5y ago
(This should be with a reason e.g. if you're working on a part that you don't know too well, trying to learn how it works)

thrower123 5y ago

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.

restalis 5y ago
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.

mbrodersen 5y ago

People do what gets rewarded. People stop doing what gets punished.