17 ms·
High-documentation, low-meeting work culture
- oxff 4y agoWhat about the low doc, low meeting culture
- twobitshifter 4y agoWhat is an example of that working? Just code that speaks for itself? How would you ever know why something was done?
- DenisM 4y agoTurn around and ask. For small teams it might work well. Larger teams require more overhead, hence why hiring more people does not produce linear productivity growth.
- mobjack 4y agoYou ask someone in slack. If that isn't sufficient, set up a small 1 on 1 meeting to discuss. You can't avoid all meetings, but you can keep them few and small.
- twobitshifter 4y agoIn long running projects, the people who know the answer may no longer be around.
- Macha 4y agoNow my ability to find something is limited by someone else's availability, and everywhere I've seen this culture it's devolved into the same 1-2 people answering all the questions as not everyone has a built up map of who knows what.
- koonsolo 4y agoAfter you are the 3rd person who contacted me for the same thing, the next one better read the fking documentation that I write.
- mostlylurks 4y agoContrary to popular belief, it is almost always possible to express the 'why' (not just the 'what') via code, even if comments and/or external documentation are sometimes cleaner, simpler alternatives.
- hannasm 4y agoI have had good experiences using commit messages for documenting the reasoning behind code changes.
- willcipriano 4y agoI'd like a read the code culture. For me documentation is harder to read than code and so inaccurate that you end up reading both anyway.
- aliswe 4y agoit's a good start but it doesn't scale
- lifeisstillgood 4y ago>>> It’s not just about the meeting, which is itself a thirty to sixty-minute intrusion on someone’s day. It’s about the time wasted anticipating a meeting, where people feel they don’t have the time to plunge into an important project. Oh god yes! This - a thousand times this !!
- holoduke 4y agoDocumentation is worse than code. It's often outdated, difficult to understand and full of useless information. In every company I have been people hate to read docs and nobody wants to maintain them. I am not sure what a good alternative might be.
- KaoruAoiShiho 4y agoIt just needs to be better than meetings to be well, better than meetings. Nothing is worse than meetings.
- dist1ll 4y agoThat's a culture problem. It boils down to documentation being a second-class citizen which is not included in the "definition of done".
- dsugarman 4y agois this the anti-agile manifesto? Personally, I think they got it right the first time (https://agilemanifesto.org/ https://agilemanifesto.org/), even if most modern agile application feels pretty anti-agile today
- Delsonic16 4y agoI've been working with Tremendous and have become a believer in high-documentation, low-meeting work culture. Employees are happier, more productive and have more head space to develop creative contributions.
- Charlie11 4y ago
- ifloyd 4y agoOur work culture's obsession with meetings, which is dwindling, it seems, is due in large part to our desire to perform as part of 'productivity theater.' this has mostly been driven up by wfh. but it's interesting to me that so many people focus on performativity vs. output
- thisisbrians 4y agoI think about this a lot. "Managers" are under pressure to make sure their teams are meeting goals/deadlines/whatever, so they are anxious, so they make efforts to observe and oversee "performance". Seeing people in meetings and diligently "working" makes them feel better about their teams' performance. But what really matters is outcome...which is very difficult to measure for a lot of software teams, and even harder for individuals. The irony is that the efforts to measure/ensure performance, in many cases, actually impede material progress towards the desired outcomes.
- ip26 4y agoOn the other hand, thirty minutes a week seems like a small overhead to pay if you’re concerned a team might otherwise lose focus & direction entirely. Not, to be clear, that they are lazy, but instead that they could be diligently working… on the wrong thing. I can understand it both ways.
- thisisbrians 4y agoIt's certainly a spectrum. 1<>1s and vision alignment meetings are super important. Standups too, if that's your thing (I like them, but they must be run well). A lot of other stuff can start to get noisy in my opinion.
- lambdatronics 4y agohttps://dilbert.com/strip/1995-02-17 https://dilbert.com/strip/1995-02-17
- uxp100 4y agoIs it dwindling? I think the number of hours of meetings I attended approximately quadrupled due to WFH. Limited conference rooms making > 1 hr meetings impossible was wonderful. Or are you saying it was dwindling, but it surged up due to wfh? Then I guess I agree, though I’m not sure if it’s due to productivity theater, or physical constraints being removed
- cateblanchett 4y agoi personally can't retain any information in meetings, and i've honestly watched meeting recordings back to take notes on important info that i totally glazed over at the time. this wastes a total ~121 minutes on average, based on their estimate of time it takes to refocus after meetings.
- dottedmag 4y agoIs there a way to stop scrolling hijacking on the sites like this one?
- cosmotic 4y agoadblock all the scripts =/
- informalo 4y agoWith uBlock *SmoothScroll*$script
- Sohcahtoa82 4y agoHonestly, if it wasn't for the fact that setting up a build environment in Windows is a god awful experience (As opposed to *nix where I can just "apt install <whatever>lib-dev", I'd fork Firefox and make a build that strips out access to scrolling in JavaScript. Dear Web Devs Every web browser already does smooth scrolling out of the box. Your JavaScript implementations of it rarely work and only create frustration to users. Even they they DO work, it creates an unexpected behavior, which is frustrating.
- agtorre 4y agoI've also seen a lot of benefit of grouping recurring meetings all in the same time slot daily. I.e. all team rituals from 10-11 am daily.
- skagenpilot 4y agoThis reminds me of Alan work culture [1], Alan is a startup with a zero meeting policy and a very strong culture of writing. They check the quality of one's writing during their interview process. Alan leaders also have other strong ethos like "no managers" and "complete transparency". I really wonder if these companies are exceptions or if this organisationel model could be replicated more widely. I guess it caters to some very specific personality types. [1] https://blog.alan.com/bien-etre-au-travail/who-we-are-and-how-we-are-building-our-culture https://blog.alan.com/bien-etre-au-travail/who-we-are-and-ho...
- dia80 4y agoTo me, some of the benefits of having the occasional meeting is to create a shared understanding of what's going on and also to enable a vigorous group discussion. I'm not sure I would know how to replicate that with writing alone.
- Frotag 4y agoChatrooms for each team, but visible to other teams. And a culture of encouraging technical discussion to be summarized or at least alluded to in the public chat. I'm sure this doesn't scale, but for a company of <20 developers, this worked amazingly. It was also great for finding answers to silly questions without having to bug someone.
- impute 4y agoThere's nothing on that page that mentions "no managers"
- synu 4y agoAt my company we make all meetings optional, this really helps create the right incentives both for hosts and attendees. As a result we have very few meetings, but the ones we have work well. https://www.synura.com/handbook/general/meetings/#all-non-11-meetings-are-optional https://www.synura.com/handbook/general/meetings/#all-non-11...
- bergenty 4y agoAs someone that hates taking a long time to write documents and has similar resistance to reading large technical documents I much prefer to ask my specific questions in meetings. I retain the information much better that way.
- civilized 4y agoMy experience with meetings is that they're effective at getting people to nod their heads and say they get it, but when it comes time to actually do something, they'll be back at the expert's desk needing to go over it again. Then again, documentation doesn't necessarily solve that either, because then you have the people at your desk who don't read the documentation and need someone to walk them through it. But at least that way you don't have to go from memory.
- tqi 4y agoSounds like this works great for them, and an awesome environment to be a part of. However I'd be very curious to see how this evolves as the company grows. Personally, I am skeptical that this is sustainable in the long term. In my experience, most people are a) bad at writing and b) hate reading. And as a company grows, and the number of documents that need to be written and read explodes, this work pattern eventually becomes untenable. More and more meetings get scheduled to cover topics that are not well documented, which causes people to have less time/inclination to create or consume high quality documents, and it becomes a feedback loop. (Edited to make it clear that I am not against the idea, just curious to see how it evolves)
- epolanski 4y ago> a) bad at writing and b) hate reading Why does everyone else has to pay the insane price for that?
- cateblanchett 4y agodoesn't Amazon have a similar structure, tho? i don't know what it's actually like to work there (anyone who does feel free to chime in) but i've interviewed and from what I can tell they put a heavy emphasis on documentation. it's tough to find a bigger and more siloed company than Amazon, and it seems to work for them.
- erichocean 4y agoAs someone who has to use Amazon's external documentation: it's absolutely terrible. Worst docs of any company we have to interact with at the API level.
- MikeMaven 4y ago
- fumar 4y agoAmazon is high documentation, high meetings culture. The documentation is reviewed by peers, bar raisers, and leaders in a process called document read before being official. Edit: Someone asked for more detail on high meeting culture. There are constant meetings between cross-functional teams, various leadership stakeholders, and ongoing operational planning. That is not including your day to day meetings within your sub team or the follow up meetings from doc reads or the new team launch meetings, etc. Amazon tech is a high meeting culture.
- jl6 4y agoHigh-Documentation is so out of fashion, for all the wrong reasons. If you are designing anything that is intended to last longer than 6 months, documentation is a critical part of the system. Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet joined, and do them a favor by writing things down. Ability to use written communication is a major differentiator between junior and senior engineer.
- icedchai 4y agoWriting is definitely a critical skill for software development. At my last "staff+" job, I spent most of the time writing documents that seemingly nobody ever actually read. I also reviewed a bunch of them.
- justin_oaks 4y agoThis reminds me of when leadership announces a policy over email. Sure, all the people who got the email can follow it, but what about people who join the team in the future? Either they find out about the policy when they violate it and get reprimanded, or they hear about it via word of mouth. I've seen it a number of times in my career.
- fool1987 4y agoFor sure! Why can't it be "we have updated/created X policy, please find it here: <link to document in policy repository>" ? Is that so much harder? Most document management systems have a notification system built-in so that you can automatically email your all-staff mailing list when there is an update. It's very much a solved problem.
- fool1987 4y agoHard agree. My current workplace culture (at least in the HW dept) is much more towards zero-documentation than anything I have experienced before and it has been a nightmare as a relatively new employee. I waste so much time in reviews because I have done something non-standard despite having checked the standards docs but it turns out the standards have changed and no one bothered to update the docs. We don't even write specifications for products before we start work on them; if I make some architectural changes during the design, there is nowhere to record it. Drives me insane. IMO there are two things that should be documented about any project: 1. The product itself: at least its interfaces, features and general architecture 2. The process of design: what changes were made vs the original spec, why, and when If you want to know anything contained in that set of information here, you have to know who worked on the project so you can ask them about it, and then they have to be able to remember. It's not uncommon that changes are suggested and discussed multiple times within a project, or that changes are made but the reasons why are forgotten before the project is even complete. I often joke that projects here are more "observed" than managed. Exactly as you say - emails/meetings are ideal tools for discussion and decision making but for lasting records, you need documentation.
- krapspark 4y agoI wanted to read this article but the sluggish scrolling on the page made me leave the site. I appreciate the approach in the first few paragraphs I read, though. haha
- willchis 4y agoThe motion and blurring made me feel sick so I quit reading too!
- bluetomcat 4y ago"High-documentation" isn't the cure, either. Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes. I want to be able to build the thing without frustration, to start playing with it in order to learn its internals and debug it. Only then can I be comfortable enough to start implementing features and changes.
- giogadi 4y ago"Just write quality software" That's quite a load-bearing "just" there.
- rqtwteye 4y agoIt's devastating to learn after more than 20 years in the industry that the secret is "Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes". If I and my colleagues had known only sooner about this straightforward and actionable advice...
- DenisM 4y agoThat’s how I often use documentation - start documenting something, then ask myself “should the code be fixed to avoid the need to document this part? Yes, yes it should”. A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.
- ip26 4y ago
- nisegami 4y agoIn order for this to work, you also need a high-reading work culture, which is distinct from a high-writing (documentation) work culture.
- seltzerboys 4y agowell if people choose not to read or engage with documentation, they're only hurting themselves. in theory, their work performance will suffer when compared w/ others. and if it doesn't, then they for some reason just don't need to engage with existing documentation, so high-reading wouldn't really matter. the consequences of not reading documentation will either become clear or it won't
- xapata 4y agoPoor work performance hurts everyone.
- fool1987 4y agoAs the only person on my team who routinely documents my work (or at least who does so in a place visible to others), I definitely agree. I get very tired of people asking me things about my work where the reply is "it's in the docs, please check here: <link>." Makes me feel like a directory.
- RugnirViking 4y agoas someone who often would like to read documentation but have to end up asking the owner where it is like you describe My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noone has looked at it in a few months so its an ideal candidate for this kind of knowledge. Despite that, I didn't go to confluence, because 99% of the stuff on there is half-finished drafts, and stuff aimed at our b2b customers, so I don't hold much hope in finding a solution to something which in principle ought to be very simple, like setting up my dev environment. In this case, the original project lead is no longer with the company, I had to ask a couple people who worked with it in the past, and it turns out they no longer knew how, and the documentation which had been written both didn't include it (it was customer-facing) and was also so out-of-date as to be irrelevant. I have no doubt that whatever developer made the app stopped writing documentation because they felt nobody would read it if they did! it's a self-reinforcing cycle. I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.
- canucklady 4y agoMy current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a specific, obscurely named document in Google Drive, Confluence, or Github. We've tried a bunch of search tools which successfully surface the million product documents, design documents, PM reports, planning docs, retro docs and standup and oncall notes related to any feature, none of which are up to date.
- sdflhasjd 4y agoIt's actually hilarious how Google - a company famous for it's search engine - made Docs, who's search function cannot find anything.
- crazygringo 4y agoI live and breathe using Google Docs search functionality. It's my main way of finding files scattered across 10 years of folder hierarchies. It works great. What do you mean it can't find anything?
- sdflhasjd 4y agoWhat I find is that it's very "dumb", almost "... WHERE filename LIKE '%query%'" dumb. Example might be searching for "<Cool Project> Technical Spec". - Can't find "Technical Specification" in the "<Cool Project>" folder. - Can't find "Tech Spec" (and vice versa) - Can't find "<CoolProject>" Is there some "enable real search functionality" checkbox I've missed, or am I just doing it wrong?
- crazygringo 4y agoYeah, I think you're "doing it wrong" as much as I hate to say that, sorry. Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in. The main thing to keep in mind is that search is content-based, not just filename. So instead, search for key terms you think are in the file, as opposed to focusing on folders/filenames. Start with one or two, then modify or add as necessary to narrow down.
- intelVISA 4y agoRecently I've only worked for companies with limited (1 max) meetings for ICs a week, I definitely recommend it.
- pigsinzen 4y agoIs the lack of "meetings" offset by pair-coding, dragging out synchronous conversations in Slack, or otherwise controlling engineering time and schedule?
- intelVISA 4y agoNo, (currently) fully async as long as deliverables are met. The extent of 'controlled' engineering time is requiring 1x code review from a different SWE to merge a PR which is also async via GitHub comments.
- pigsinzen 4y agoAhh nice! I was recently on the market and had nearly no luck finding a culture like that which matched my skill-set. I am envious.
- intelVISA 4y agoIt's still quite rare unfortunately, and there are still negatives: less time in meetings means more time actually working which isn't always what you want! Though it's offset by very generous comp as there's not as much bloat to soak up your TC. So YMMV...
- AlexTWithBeard 4y agoMost of documentation I've seen is either not yet finalized or already outdated. Often both at the same time.
- incomingpain 4y agoSounds like my current job which I love. My last job, low documentation, low meeting. Basically every bit as bad as you might expect. Every job you basically have to figure everything out from scratch. 2 jobs ago, low documentation, high meeting. Daily meetings to discuss what I'm working on and how little the rest of the team is doing. Yet nothing changes or improves.
- manv1 4y agoAll developers should spend time working in support. That time will make them appreciate the incredible power and utility that documentation provides to everyone...including your future self.
- convolvatron 4y agoI find it to be really interesting for the first day or two...then I realize that our customers are often really terrible people using our product for really bad reasons and it undermines my whole faith in the project
- manv1 4y agoYeah, that's the downside to learning about end-users. But it's better to know than to be ignorant, usually.
- thenerdhead 4y agoI wish more people adopted Andy Grove's thoughts on meetings. https://jondouglas.dev/lets-not-meet/ https://jondouglas.dev/lets-not-meet/ This company seems to "get it" though. We ought to protect our attention more often. I'd take documentation over no documentation any day. Even if it's 4 years old and was last updated by a person who left for a competitor.
- DenisM 4y agoI read through your link and it rang hollow to me. Care to share your insight?
- thenerdhead 4y agoMy blog is the insight. The book I recommend may give more context as to why it is important.
- cokeandpepsi 4y agoto many meetings -> not getting enough done -> hiring spree -> even more meetings -> reorgs to nowhere -> layoffs
- ChrisMarshallNY 4y agoMy personal policy was "No regularly-scheduled meetings" (which included things like daily standups). But I worked for a Japanese corporation, so we had regularly-scheduled meetings. I was able to reduce them, though.
- fragmede 4y agoI was recently introduced to www.Loom.com which is this fremium screen recording app and website (no affiliation). Being able to have a certain type of meeting asynchronously has been a boon to productivity. The async nature of texting is great and adding the same thing for audio and video/screen recording has been similarly great.
- beckingz 4y agoPersonally, I do not like video recordings. I find them inferior to text communications in terms of maximum bandwidth and bandwidth to cost ratio (time to write and read). However, some people are much better at communicating or understanding material if its shown visually, which can be much more time efficient for both parties sometimes. Every format has a place.
- drstewart 4y agoVideo recordings shouldn't necessarily replace written messages, they should replace video meetings.
- Eleison23 4y agoMy job is sweet. The management really doesn't go in for meetings, especially not all-hands, nor 1:1s for us at the lowest level. We have onboardings and special messages and all those are recorded in case someone misses, it's no big deal. Documentation: we have a master SOP document that's about a dozen pages, you can read it in an hour and understand it. There's a living spreadsheet that's updated so you have to check it on the regular. I've also helped build an aid for one particular investigative side, but it's optional. There's other documentation but it's all ancillary and optional, the biggest thing to know is SOP. There's an #important-links channel on Slack and I do try to look through it on the regular, but all you really need to know is a small field. We're all 100% remote, WFH team. We stretch from San Francisco, to NYC, to South Africa and coworkers in Australia too. We're starting to branch out in non-English languages, so I'm sharpening my Spanish for the road ahead.
- deleted 4y ago[deleted]
- maximus-decimus 4y agoI was watching a DistroTube video where he was ranking multiple windows managers, and he explicitly refused to give i3wm points for having great documentation because "it's the bare minimum". Except all the other ones had crap documentation. One can only dream everything had documentation as great as i3wm's as a bare minimum.
- blueboo 4y agoI love the idea, but we should be taking pinches from our fancy sea salt. Tremendous has less than a hundred employees. Just small enough that people can probably individually track the complete state of their respective arm of the business. Marvelous is also about to face a significant stress test with the holiday season, both from retail usage of their product and from vacations of their employees. I wonder how routinely highly-documented the agendas will be when competitors start sniping their biggest clients as their service crashes from overcapacity. Reversion to the mean is coming — what would be interesting would be to hear successful strategies to resist it.
- origin_path 4y agoI tried to create this type of culture at my last gig, where I had the unusual privilege of being able to hire almost the entire engineering team, alongside my manager who was also very document oriented. Unfortunately, it didn't work out. Maybe Tremendous has done tremendously better, it's certainly possible, but here is a list of things that went wrong, maybe it's useful. 1. Standard interviews don't assess reading/typing speeds. If you want a high documentation culture this is critical. It took way too long for us to figure this out but many people in the company were significantly slower at reading/typing than us; they found long documents overwhelming and would find excuses to not read them. Slack conversations became a massive sore spot because unknown to us some people felt like they couldn't keep up. They'd try to type a question or response and we'd already posted another two paragraphs before they got a chance to finish their thought. They'd complain to each other that if they asked us a question they got back an essay in response, etc. 2. Documentation requires ownership, otherwise it rapidly becomes useless. Standard corp tooling like wikis doesn't make such workflows easy. They are however optimal from a corp politics perspective (dispersal of responsibility). Maintaining markdown based websites works well as long as you have empowered maintainers who view document quality as a core job function, but you have to force people to submit changes by e.g. rejecting at code review time changes that don't update the docs. People will moan. They will ask you to do it for them. They will submit absolutely min-viable docs changes, they will demand you hire technical writers even if they're easily capable of doing it themselves. And of course the moment you're not using a git-style workflow, just forget it, you have no chance of preserving coherency in any sort of knowledge base. 3. Lots of people aren't just slow but actively HATE reading and writing. They will make things up on the spot, or lie, or just flat out refuse to do the work rather than sit down and read a long document. Jeff Bezos has said about why Amazon uses meeting time to force people to read the memo: "If we don’t, the executives, like high school kids, will try to bluff their way through a meeting" You will have to fire people for refusing to read things if you're serious about creating and maintaining such a docs-oriented culture, which in practice is so unpleasant nobody ever does it and so maintaining such a culture is nearly impossible. You will also have to flat-out refuse to meet people in order to force them to read, because otherwise they'll receive a document and just ignore it. I had several cases where one of my most senior engineers would assert that a product we used didn't have feature X, and I had to correct him by pointing out that the user manual discussed feature X in detail. I knew this because I'd actually read the user manual cover to cover. Basically nobody does this and guess what, if you're the one person on the team who reads stuff then you're going to come across as the awkward smart alec who makes people look stupid. Sometimes, ignorance is bliss.
- jayjay12389 4y agoI think there is a trade off on amount of time spent on the high-documentation approach and how large you are. Totally makes sense for larger organisations but less so for startups. There is probably a number of consumers of the information produced at which point it makes the most sense to do go for 'high-documentation'. I wonder if anyone has done deeper research on this.
- kozak 4y ago"Unfortunately, Tremendous is not available in the country where you are located. If this is a problem, please contact support@tremendous.com." I'm in Ukraine and this is disgusting.
- cateblanchett 4y agoUS treasury department regulations prohibit US companies from working with people and companies in Russian-controlled parts of Ukraine. Unfortunately, IP geolocation is accurate only to the country level, so US companies have no choice but to block the entire country to comply with regs.
- kozak 4y agoThis is the first case I know of. I never get such issues here in central Ukraine. This is because occupied regions always present themselves as Russia, not Ukraine. If something says that it is Ukraine, it's a sure sign that it is NOT occupied by Rissua.
- SevenNation 4y agoI didn't see anything about the hiring process needed to get high-documentation culture to work. Many developers don't write well. Some don't empathize with the reader and so can't communicate complex ideas effectively. Others lack the ability to abstract their ideas. Many will be coming from the exact opposite of a high-documentation culture and so simply will not value good documentation. Asking people with poor writing skills to work in the way described here seems like it could lead to problems without a selection process favoring good writers, or at least a training system to get new hires up to speed.
- pillefitz 4y agoMany in this thread seem to conflate documentation with code documentation, while I use it as a means to communicate requirements to the developers. Some mockups here, some data description there, it makes all the difference. Our stories/tickets increasingly consist of only a title, a wiki link and some acceptance criterions. Works great for me as a PO, devs like it and provides a lot more context than fragmented tickets do.
- michael1999 4y ago+1 for all docs being public-by-default. But these are all sophisticated skills. And the broader industry does not reliably teach them. ctrl-F "Training" 0 hits. ctrl-F "Hiring" > But we take great care during the hiring process to choose people that thrive under these conditions. Is the interview by post? There's a story here, but I don't know what it is.
- DustinBrett 4y agoIt would be nice if instead of documentation, we could design things to be self evident. Feels like if you need to read the docs then the product/service failed to make it clear how to do something.
- rcarr 4y agoI'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departments add, commit and push and then show maybe one person from each department how to solve conflicts. Alternatively, build non technical people a web interface for editing and committing but allow the devs to just use git as standard. Or there's Obsidian's built in sync but I don't know enough about it to know if it scales well in large organisations. What absolutely is definitely not the solution is Confluence. I have not met anyone who has a positive thing to say about it. The only reason it is being so widely used is because it satisfies whoever is in charge of the finances because it comes bundled with Bitbucket and Jira.
- howenterprisey 4y agoI use Confluence pretty heavily at work (I write most of our docs) and I like it. Any annoying UI elements, I hide with ublock origin. I don't mind the lag, although I do wish it were faster.
- zppln 4y agoThis sounds like a programmer's rather naive take to be honest. Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).
- waboremo 4y agoAn easier one stop shop alternative is just Notion. Recommend it for the reason of having an internal wiki/documentation. Probably one of the only real use cases for Notion, everything else (like personal note taking or time organization) is horrible on it.
- rcarr 4y agoThis was actually my next suggestion when Obsidian got shot down. It's definitely a nice half way house between the two. Again it got dismissed albeit this time with no explanation, I assume because the request for feedback and suggestions wasn't actually anything of the sort but basically a pretend exercise on behalf of management to 'show we're listening'.
- Xeoncross 4y agoIf you have a high-documentation culture, you must have documentation enforcer roles. It's crazy to think you would have a library without librarians to run it. There must be people who sole role in the company is to spend time on each team (in sequence) trying to follow or review their docs and get X running "like the docs say" This group of enforcers will contain a variety of people from tech, legal, customer service, and other backgrounds who can spot trash (in their area of expertise) when they see it.
- justin_oaks 4y agoUnless the documentation enforcer has power, they'll just be an annoying voice. I don't care what that documentation enforcer has to say if my boss prioritizes code over documentation. You'd need management buy-in at every level for a high-documentation culture/company to work.
- Xeoncross 4y agoSure, replace documentation enforcer with security team. Same argument.
- baby 4y agoExactly my thought, these people will burn out and there's just no way around that. Sometimes you need people whose job is to burn out trying to pull others in one direction
- edgyquant 4y agoThe same is true for testing though. Lots of shops write as few tests as possible, if any, because the devs don’t have to so they think their way is just fine. I went from working as the annoying guy asking for tests and docs to the manager and we saw a huge improvement in performance, feature release and a reduction in bugs hitting prod. I can attest their way does not work just fine.
- baby 4y agoI really think this is true, and we usually rely on tech leaders or PMs to do this job, but in reality maybe we should consider having people who are responsible for this full time (or at least part time). I think having advocates or evangelists within the company is important also, people who can interject "good answer, I think it would be valuable to copy this in a document for the next time someone asks"
- glonq 4y agoI had the luxury of being able to document the hell out of the previous system that I worked built -- before, during, and after development. It was a refreshing change from 'just hurry up and build the damn thing'
- nickdothutton 4y agoAll the corp document stores I’ve seen, and I think I’ve probably seen most of them by now, would benefit from a full-time librarian (or team thereof) and a help-desk to field enquiries. Because you have little hope of finding what you want, even if you know it’s in there somewhere.
- DubiousPusher 4y agoI think this approach has many benefits. The main problem with most collaborations in which documents are used to replace conversation is that without a disciplined framework for structuring documents it's very easy to get lost in them. -documents go out of date, people are usually up to the minute -documents don't allow you to ask questions people do -documents never forget, people do (not forgetting seems like a good thing but try working through a 5-10 year old team wiki or OneNote and you'll see why it can be good)
- technological 4y agoPersonally I feel documentation wont be such hard thing to do if ppl are not very particular about formatting and making it look good.
- celestialcheese 4y agoFrom the outside, Gitlab seems to have solved this with a medium-sized org with all remote, and it sounds like a dream remote workplace. Async communication, full transparency, 90-day retention in slack which forces decisions into documentation if it's important, issues/threads for discussions, and handbook for SOPs [1] Anyone have experience with this directly that can speak to if this works in practice? Or is Gitlab just really good at marketing their methodology as a tool to sell more subscriptions? 1 - https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/ https://about.gitlab.com/company/culture/all-remote/handbook...
- peterbozso 4y agoGitLab employee here. Can confirm, it works exactly as advertised to the outside world.
- alohaandmahalo 4y agoGitLab team member here for over 3 years. Can confirm, it works exactly as advertised. The detailed description above is totally in line with my experience. The two essential elements of why this works. 1. Communication (both formal — work related — and informal) is explicitly defined. https://about.gitlab.com/handbook/communication/ https://about.gitlab.com/handbook/communication/ 2. There's absolute executive sponsorship to work "handbook-first." If it's not in the handbook, it's as if it doesn't exist. The top-down belief in the system enables it to function. https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/ https://about.gitlab.com/company/culture/all-remote/handbook... We recently codified the operating model in a course we're calling TeamOps. It's a first iteration, but anyone is welcome to take the course and provide feedback. https://about.gitlab.com/teamops/ https://about.gitlab.com/teamops/
- dnsmichi 4y agoGitLab team member here. Sharing a personal insight - I'm currently moving flats in the Nuremberg area in Germany which is a little hectic because forced out by the new house flat owner. Async work enables me to take calls and go shopping to organize the move, whilst shifting work hours into the evening or early morning. I am also able to take paid time off (PTO) when needed to prepare the move early December. In my previous office job, I would have needed to reserve a lot of vacation days for this, and ask for permission to start later than 10am, or leave earlier than 4pm. Here at GitLab, I am my own manager [0] and take care about my working hours - it is a personal freedom, and I appreciate these less stressful times a lot. In return, I can take time to focus on private life, and come back refreshed to produce great results (blog posts, talks, helpful replies here and other community channels, etc.). What I learned in the past 2 years and 9 months at GitLab, is to provide as much context as needed so that someone else in a different timezone can continue async, and is not blocked by anything (low context communication [1]). Also, short toes [2] enable everyone to add their thoughts and opinions, and work with the directly individual responsible (DRI) for the best outcome. The Slack retention period of 90 days is a great reminder (and also enforcement) to document everything in the handbook. Example from today: I learned that Google docs supports the colon for emoji live-search. Thought of sharing in Slack, but then went with editing the handbook and sending a MR [3] to help everyone find this little efficiency tip in the future - that said, Slack is not a knowledge base. The GitLab handbook is. Thinking about the past year with a public discussion about speaker diversity at events, I admire our teams to take action to ensure events align with our diversity, inclusion and belonging values. We have updated our event requirements for speakers (MR [4], handbook page [5]), and are working with event organizers and the wider community to help with mentoring and coaching to inspire future speakers. Last but not least, transparency [6]. Internal and external, I can read and learn async at my own pace. Most of my meetings are optional, and the meeting notes/recording are detailed, with follow-up actions. You'll never recap old meeting notes the next time but reference actioned issues and merge requests. Many issues/epics are public - if you'd like to learn more about my thought leadership strategy for Observability, and all content created and planned, you can follow this epic [7] or my profile activity [8] for example. I haven't met everyone in-person yet, because of the pandemic, and travel only for some events (KubeCon EU/NA, PromCon EU [9] [10]), but I am looking forward to meet and value these moments. Hard to describe, I feel incredibly connected to my teams albeit living far far away. :-) Happy to share more thoughts and insights - my role is on the community relations/developer evangelism team, I'm the stable counterpart for the product teams, and collaborate in cross-functional initiatives often. [11] My first [12] and second [13] year blog posts share more experiences too :-) [0] https://about.gitlab.com/handbook/leadership/#managers-of-one https://about.gitlab.com/handbook/leadership/#managers-of-on... [1] https://about.gitlab.com/handbook/communication/#effective-communication-competency https://about.gitlab.com/handbook/communication/#effective-c... [2] https://about.gitlab.com/handbook/values/#short-toes https://about.gitlab.com/handbook/values/#short-toes [3] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/115426 https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request... [4] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/106770 https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request... [5] https://about.gitlab.com/handbook/marketing/corporate-marketing/speaking-resources/#event-requirements https://about.gitlab.com/handbook/marketing/corporate-market... [6] https://about.gitlab.com/handbook/values/#transparency https://about.gitlab.com/handbook/values/#transparency [7] https://gitlab.com/groups/gitlab-com/marketing/-/epics/2593 https://gitlab.com/groups/gitlab-com/marketing/-/epics/2593 [8] https://gitlab.com/dnsmichi https://gitlab.com/dnsmichi [9] https://dnsmichi.at/2022/06/13/my-kubecon-eu-experience-first-time-in-person-meeting-friends-and-speaking/ https://dnsmichi.at/2022/06/13/my-kubecon-eu-experience-firs... [10] https://opsindev.news/archive/2022-11-23/#promcon-eu https://opsindev.news/archive/2022-11-23/#promcon-eu [11] https://about.gitlab.com/handbook/marketing/community-relations/developer-evangelism/#-team-members-and-focus-areas https://about.gitlab.com/handbook/marketing/community-relati... [12] https://dnsmichi.at/2021/03/02/my-1st-year-all-remote-at-gitlab/ https://dnsmichi.at/2021/03/02/my-1st-year-all-remote-at-git... [13] https://dnsmichi.at/2022/03/02/2-years-all-remote-and-2022-vision/ https://dnsmichi.at/2022/03/02/2-years-all-remote-and-2022-v...
- _def 4y agoI'm desperate for less meetings. How do you fight against Scrum? It seems like at some companies it's the only way they know how to "get things done", even if it doesn't really work
- hackeredje 4y agoDocumentation should be atomic, not large pieces of text. And each atomic item has bidirectional dependencies to other atomic pieces or methods or classes or requirements or terms etc.
- chupchap 4y agoFrom my experience effective written communication and good comprehension are rare skills. That's the reason meeting culture is so resilient.
- goldenshale 4y agoIf only we could have an AI do the documentation...
- deleted 4y ago[deleted]
- nesarkvechnep 4y agoI thought high-documentation would be related to literate programming. Joke's on me, looks like we're going to try to reinvent LP forever.
- throwawaaarrgh 4y ago1. If you want this culture, make it a rule, the way GitLab did with their Handbook-first Culture (https://about.gitlab.com/handbook/handbook-usage/#why-handbook-first https://about.gitlab.com/handbook/handbook-usage/#why-handbo...). 2. Do not expect anyone to do anything you have not trained them to do. If you want your employees to work this way, actually train them on how to do it. 3. Without leadership pushing this culture, it will. not. happen. Don't even suggest a change like this until you have sold at least 3 people in leadership.
- divbzero 4y agoI like this a lot in principle but would add two notes about doing this in practice: 1. Promote self-documentation as much as possible—e.g. meeting notes typed straight into Google Doc, discussions typed straight into Slack, issues typed straight into GitHub, comments typed straight into code—so you’re documenting as you go in a way that’s automatically archived and searchable for future reference. There are times when separate out-of-band documentation is appropriate, but that takes extra effort and can get out-of-date more easily. 2. Promote an it’s still okay to ask culture in parallel with the high-documentation culture. Asking questions in Slack can be a shortcut to finding the right document or finding out something is yet undocumented, and should be encouraged especially if the asker has already done a quick search without locating the needed information.
- sneak 4y agoThis doesn't work at most companies because most people don't know how to type properly. Thus they would rather speak at a meeting than type into a form, because they can speak several times faster than they can type. I don't hire people who don't know how to type properly (or won't commit to learning).
- b0rsuk 4y ago
- deleted 4y ago[deleted]
- password4321 4y agoIs there any documentation system that incorporates an expiration date, forcing manual review to renew? I also am interested in ways to tie source code and documentation together. For example: linking to methods in a way that follows refactoring.
- password4321 4y agolol - (re: linking) ask and ye shall receive! Show HN: CodeLink: create links to blocks of code in your IDE https://news.ycombinator.com/item?id=33711480 https://news.ycombinator.com/item?id=33711480
- sauravc 4y agoI thought this was a well written article and I loved the graphics (especially the one about 30 minute meetings actually taking 68 minutes). However, it's worth noting that this company is fairly small (48 members according to their About page) and that the group has been together for quite some time. I'm not sure how well this would scale past the Dunbar number, or for organizations growing rapidly. Either way, I'm glad they published this.
- qkhhly 4y agoare your engineers evaluated on the quality and up-to-date-ness of the docs they produced? and are they paid more and promoted faster if they do produce quality docs? if not, i don't believe you.
- tiffanyh 4y agoI love the idea of less meetings and more documentation, but I've never seen it work. Here's a few observations... a. you need a person who "curates" the documentation, otherwise it completely loses organization quickly b. things become out of date fast and it's not clear if you're reading something out-of-date c. people write too much, meaning - things turn into this huge long form internal article and people get exhausted in just reading through it. Writing is actually quite hard. I don't have a better solution/approach to recommend (besides having a curator), but the "less meetings / more documentation" train always seemed oversold to what I've experienced first hand.
- baby 4y agoI don't think these means that documentation doesn't work. It means that while documentation works, there's a number of additional issues that you also have when you use documentation. Try having no documentation instead of disorganized or outdated documentation. I'll take the latter.
- vonnik 4y agoI've worked at high-documentation companies and low-documentation companies. Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much knowledge is trapped in the analog world, and in peoples' minds. Companies like storytell.ai are trying to solve the problem of creating documentation and written artifacts automatically out of Zoom recordings, etc. Others, like WeRice, are trying to create it out of videos of maintenance work done on equipment in the wild. I respect both efforts a lot. It's a hard problem to tackle. * https://www.storytell.ai/ https://www.storytell.ai/ * https://we-rice.com/ https://we-rice.com/
- pessimizer 4y ago> It is essentially a simulation of an underlying reality, and that underlying reality always changes faster than the documentation can. That probably depends on how you prioritize it. You can dictate that the docs (and the tests) be written before features are added.
- Nevermark 4y agoThis can be improved with two sets of links for each doc. A set of manually added links to previous related material, with optional note. New links can be added by anyone. And a set of automatically generated reverse links, to documents that referenced the one being viewed. Both kinds of links help create continuity and context.
- vonnik 4y agoAgain, that a lot of extra work, and the automatic reverse links are v tooling dependent. You don't get them with Confluence or gDocs, fwiw. Nor do these suggestions solve the problem of doc creation. What many people ignore in these discussions is the real tradeoff between "time spent in meetings with people who can answer questions" vs "time spent by non-professional writers trying to be clear for strangers".
- bluedino 4y agoOh my god, that font.
- nichochar 4y agoMoving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly. I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you take a 3 page paper and condense it into 100 words. I really hated doing it back in the day, but as an adult I now am very grateful I did and wished other countries made this more prevalent.
- hobofan 4y agoVery interesting perspective! I generally attributed that more to different proficiency levels in English as a second language, rather than language-independent summarization skill, but I guess that's also a realistic option.
- ch4s3 4y agoI had to do this for an undergraduate business degree here in the US and it feels like a super power working in software.
- mradek 4y agoIn America when we can’t explain something we print more money and redo the solution. Often creating more problems but that’s our flywheel we’re talking about!
- njarboe 4y agoTeaching how to write summaries in the US would be a good idea. To make things even worse, in the US most essays are assigned a minimum length so students learn to pad their writing with lots of fluff and circumlocutions.
- qwertygnu 4y agoPurely anecdotal, but I recall plenty of summarizing assignments, along with other reading comprehension tasks in my English classes. Though you're right about the minimum length padding thing reinforcing the opposite skill.
- lemax 4y agoI love companies that can actually thrive with this way of working but it only works at a certain size. This only works in a senior heavy, relatively flat engineering org. Once process ramps up due to new compliance demands or HR wants more of a mixed skill level in engineering, rapid fire product delivery and async culture dies out. I think this could be sustained in a software company in the right context, but orgs eyeing unicorn valuations or headline exits only leverage this way of working until they need to recalibrate.
- satisfice 4y agoHere is my summary of the content of this piece: "We only hire introverts who like working in introvert ways. But we like to pretend that we are just normal people who have stumbled on a better way of working that has mysteriously eluded all the other smart people in the world."
- techsin101 4y agoUnless entire team is spending 2 days on docs every week, docs are hell. I prefer comments in the code.
- hendry 4y agoLow trust, poor communication = low documentation, high meeting. I work as a consultant with a lot of outsourced teams who poorly communicate or seem to avoid written responsibility. really like that thought: "low-meeting culture allows us time to do high-value tasks"
- langsoul-com 4y agoSounds like a great place to work. Makes more sense for 100 people to read a doc and get the gist. Rather than interrupting the dev 100 times.
- deleted 4y ago[deleted]
- splittingTimes 4y agoIs there any way to achieve this within Microsoft's suite? Sadly we adopted Microsoft O365, SharePoint, Teams. How can you organize the org effectively is beyond me, how does MS do it? Are they actually using their own tools they sell others? In our org, some departments/teams/sites have just a SP, Others have a teamspace with separate SP/document store. Worse, any meaningful file structure/hierarchy you come up with gets sabotaged when new channels are created as they automatically introduce new folders. You cannot bind a teams channel to a separate folder in a SharePoint. Also, We have private project teams springing up and large fragmentation of information. If you do not know that a certain project space was set up you cannot find or join it. Going with a "single Teamspace" for the whole org doesn't work either without being able to have nested channels/groups. The org is too large and complex. I'd love to have a gitlab style handbook to be used in our org to organize knowledge and information, but I do not know if and how it could be set up technically.
- eisa01 4y agoWe use a shared OneNote, team of 20-50 Easy to use, desktop app, search, and crucially highlights new changes and additions so you can see something is updated
- peterbozso 4y agoEx-Microsoft, current GitLab employee here. The way you describe using Microsoft's tools in your company is pretty much how things worked at Microsoft while I was there 3 years ago. If you'd like to build a handbook similar to GitLab's, this page of our handbook can be a great starting point: https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/#tools-for-building-a-handbook https://about.gitlab.com/company/culture/all-remote/handbook...
- splittingTimes 4y ago> The way you describe using Microsoft's tools in your company is pretty much how things worked at Microsoft That is mind boggling. How on earth can MS have an efficient knowledge management with this setup? How frustrating was it too use for you? The most sensible way forward seems to me would be just set up a single company SharePoint with a doc store with a predefined data layout. No associated team space around that. Move communication 100% to slack. Link / pin the relevant SP folders to the slack channels. Just for the dev team this would work as we never moved chat from slack to teams. But we need to 1. interact with the less technical parts of our org (product management, quality & regulatory, BI, V&V, Legal etc) 2. Interact with colleagues from other subsidiaries. They all use teams, so conversations & especially meetings will happen on teams, people will still store docs and notes there just out of convenience or lazyness. I do not know how to solve that conundrum.
- Ginger-Pickles 4y ago> We deliberately encourage people to create documents rather than build slide decks. Slide decks can mask poorly-written content with decorative font, sleek formatting, and compelling images. >In a document, the content is all you have. It forces people to focus on communicating their ideas as clearly as possible.
- rkagerer 4y agoIf anyone who works there is reading this: There must be a spectrum of documentation-generating talent on staff. Have you ever had to read through the product of someone who isn't very good at writing it? How do you cope with mediocrity in that skill? (Is it sometimes cause to let someone go?)
- SilverBirch 4y agoThe problem with attempting a high-documentation culture is that it's very difficult to have a closed feedback loop. I see this all the time. Someone writes up "Here's what tool X does, and here's how to use it", and it never works. There's always some environment variable you forgot to set, or some local file, or some path that's literally /home/$USER/... in the code, or even worse "Here's the built binary, which isn't the same as the binary that gets built from source". How do you fix this? As part of your documentation process you get someone else to actually read and reproduce and review the document. And that person needs to be at arms distance to avoid shared knowledge being elided. To enforce this you also probably need it to gate atleast reasonably large PRs. You need ways to ensure the documentation doesn't go out of date. What am I saying? This only works in a process heavy environment. Which goes directly against what the author of this article says - which is a red flag. What can easily be the case here is you have 50 engineers all building new stuff, all writing reams of documentation which probably isn't at all useful, but because no one ever reads any of it, you never pay the cost... Then you hire someone and for the first 6 months their life is hell until they clock on to what everyone else is doing and just ignore whatever everyone else is working on and plough their own furrow. Sure, we've now got 17 different poorly documented logging libraries (because no one wanted to invest in adopting anyone elses), but every individual developer is writing plenty of documentation! Oh and god forbid you disturb the author with questions outside of the 1 very short window for meetings in 1 specific time zone. Their careers page says "Join teammates from Hawaii to Brazil to Germany". Their meeting time is 6-9pm in Germany every day and 7am to 10am Hawaii time.
- viridian 4y ago> 5 minute read Either the author is some kind of reading savant, or this metric is way off. That's over 400 words a minute for a semi-technical persuasive essay, with multiple graphs. I know there are marketing analytics out there saying that you must write everything in a 3-7 minute read band to maximize audience reach, but I don't think just telling people a long article is short is a good way to go about that.
- enson110 4y agoThe real problem is the document quality. Most of time reading a low-quality document will waste plenty of time while talking or meeting is more efficient than reading a misleading document. The other problem is that is hard to keep the document ‘fresh’, and this will lead you in the wrong direction which is wasting time.
- zach_garwood 4y agoAny documentation I can't check into the git repo is useless to me.
- deterministic 4y agoI work for a low-documentation, low-meeting company. It works great. We are routinely competing and winning against large international companies.