13 ms·
Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next
by nomilk 1y ago
Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.
- euroderf 1y agoAsk the guinea pig (read: victim) also to think aloud.
- BiteCode_dev 1y agoBasically, ergonomic testing, but for your doc instead of your software.
- Our_Benefactors 1y agoFully agree. Good docs are essential for scaling a team beyond the first few hires. I always make a point of filling in all the gaps I had to gather myself during my onboarding, and ask the next hire to do the same (and carry it to the next hire, and the next) this helps keep the docs up to date with the relevant knowledge since it’s always being filtered through the lens of a brand new computer and a dev with minimal context.
- fragmede 1y agoTotally. Something that I see a lot is software that tries to read a config file during startup that bails out (sometimes with no error message!) if the file doesn't exist. Or tries to write the config file into a directory that doesn't already exist. I'll get things working locally first, but I always have to test it in docker/other fresh test env (Vagrant), just to be sure I haven't committed the same sin myself.
- jiggawatts 1y agoYou can achieve a lot of this by creating a blank virtual machine with "just the operating system" as a starting point and stepping through your own instructions from there. My ideal state is that for my kind of .NET work, it should be sufficient to simply install the latest Visual Studio, check out the Git repo, and press "play". That's not always possible, so then the exercise becomes to simply document each step, ideally with both English words and a CLI snippet.
- mixmastamyk 1y agoIndeed, snapshots are an amazing friend for this.
- mlyle 1y agoI agree that testing from a vanilla machine is important. But there's also that your language to the user doesn't necessarily say what you think it does. You can't read it from the position of someone new. Only someone new can. And a set of commands to paste to CLI isn't the full extent of what we usually mean by documentation.
- BrouteMinou 1y agoYes, more of this! I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md. If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...
- Nab443 1y agoWhen I type F5, my terminal writes "~" but nothing happens, what did I miss?
- zahlman 1y agoIn case you weren't attempting to make a point through irony, GP appears to be using "F5" informally as shorthand for "instruct your IDE to attempt to build and run the code". Presumably, that kind of documentation wouldn't normally literally say "F5" there unless a specific IDE had already been prescribed. The point was simply that the user shouldn't be required to do anything manual to set up the code, when starting from scratch, except perhaps to authorize the automated setup procedure.
- bryanhogan 1y agoSo doing the basics of product design? :D Sounds like a good approach! Sadly user tests or other forms of iterating are often overlooked. The golden rule: Plan -> Act -> Test -> Repeat
- NitpickLawyer 1y agoWe're quickly approaching the point where you can have an LLM do this, and if it passes "the doc passes", if not, time to edit.
- rossant 1y agoI was gonna say this. Really good idea. Having an LLM go through the docs and try to implement something. Challenge would be to prevent it from using any prior knowledge or experience, depending on the docs target audience. Good prompt is essential.
- Peteragain 1y agoThoroughly agree. Where I come from it's called "shoulder surfing". It is really important to not help.
- ocimbote 1y agoAny kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (trust me :). Writing documentation is hard. Start with: Who am I writing this for? edit: I may have misunderstood OP's "with minimal expertise" for "total beginner". They're two different things, absolutely.
- bruce511 1y agoI was gonna write something similar. Know the audience. I've also come to the conclusion that "total beginners" (and certainly "minimal expertisers") didn't nowhere to read the docs anyway so it didn't matter. In other words, people who are used to reading docs can read (good) docs just fine. Yes, of course, good docs are a must. They are critical to success. But not all docs have to explain how to use a right-mouse button.
- Schiendelman 1y agoFor most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.
- derf_ 1y agoI cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places). And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.
- 1y ago
- tetha 1y agoThis is our documentation workflow as well: Write it, and then have someone less or not experienced with the system execute the runbook. Also, encourage everyone to work on refining and improving the docs, because after 5 years with a system, I will have blind spots someone less experienced can point out. On lesson I've learned from that: It's a lot about managing confidence of the user. To do this, the instruction of "invoke this shell command" is now usually accompanied with a number of sections collapsed by default: How does a successful invocation look like - especially if it contains "ignorable warnings"? What errors could occur, and are they fatal or can they be fixed on the fly? Some more complex shell-stuff is often also accompanied by an explanation of what all of this is. And yes, this means that sometimes one step in a runbook has a page of documentation if you read it all. But we've found that this helps a lot during onboarding new team members, as by now, a lot of the standard runbooks are also a prety good introduction to the quirks and quarrels of the normal tools we use.
- a_e_k 1y agoA good first exercise for new hires! (And I say that as having been both a new hire who's updated the documentation after trying to execute it, and as someone who's guided a new hire when the documentation proved inadequate.)
- golph 1y agoI'm a Jr. sysadmin at a medium sized software company. Whenever I document workflows for our users, I have two colleagues of mine who have no connection to IT work through them and add the small gotchas they asked me to the docs. It saved me a whole bunch of headaches for when other users get enrolled in these workflows.
- dendrite9 1y agoI've been doing some cal/QC functions recently after years not touching it. Since I last did it I've forgotten some of the knowledge that is just assumed. The answers to my questions are documented, but not in a places that is accessible from the production side and has lived as community knowledge in production. I've been making a list and updating the documents to fill in some gaps. Unfortunately some of the production people aren't comfortable enough pushing for changes in the documentation so some of my job now is to ask what they've noted and get it added.
- IanCal 1y agoI worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.
- jen729w 1y agoFunny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written. Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions. I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. It didn't make sense, but it's what you had to do! So these guys tried to 'fix' it, and in doing so, broke it. The whole support model was predicated on this idea that the 3rd level guys would write stuff that the 1st level guys would slavishly follow. It never worked.
- polymatter 1y agoMaybe being able to follow a set of (seemingly silly) instructions should be part of the interview/onboarding process. And emphasised at job performance time.
- bluecheese452 1y agoProblem is a lot of times silly instructions are silly because they are wrong. Like why did you turn left and try to drive through that river? Those instructions assumed a bridge was there but it washed away 10 years ago. A new bridge exists, you can see it, obviously take that one instead.
- ptx 1y agoYou could probably fix this, to some extent, by adding a sidebar to the instructions that 1) acknowledges that the procedure doesn't seem to make any sense, and 2) points out why the seemingly obvious fixes won't work. That's usually immensely helpful to me as a reader, so I don't have to waste time wondering if I misunderstood the instructions or the author misunderstood the procedure.
- Popeyes 1y agoI was talking to a friend who is a beta-tester for crochet patterns, the business owner sends out a pattern to a trusted group and the get feedback on the descriptions and the work and any things that would make it easier before they put it up for sale. I do think a lot of developer tutorials and documentation don't take into consideration that many people might not have a common understanding of terminology especially if the reader is coming across this problem or process for the first time.
- maxloh 1y agoI think the JavaScript ecosystem did a great job at this. Take a look at the documentation of React/Vue/Svelte; it is fascinating how they make it so accessible, both for newcomers and experienced developers in the field. In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.
- skydhash 1y agoThose are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)
- throwaway2037 1y agoAbout JDK Java docs: > Those are references, not tutorial. This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).
- maxloh 1y agoI also occasionally fall back to the source when the documentation isn't comprehensive enough. But as library users, we're generally not supposed to have to learn the system from its source, aren't we?
- mschuster91 1y ago> Usually you look for code examples or a guide for learning how those work ... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more. The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.
- deleted 1y ago[deleted]
- jaapz 1y agoThis is basically the user testing approach as described in "Don't make me think" by Steve Krug. You can use it to test usability of your applications as well.
- Popeyes 1y agoI was talking to a friend who is a beta-tester for crochet patterns, the business owner sends out a pattern to a trusted group and the get feedback on the descriptions and the work and any things that would make it easier before they put it up for sale.
- al_borland 1y agoI've written a lot of docs, and one big issue I saw play out over several years was watching the overall skill of the team members drop. They were told by their manager to use the docs, which they did, and then seemed unable to think outside the docs when needed. For tier 1 support roles, I think the docs were helpful to get them going, but it seemed like the docs acted as a crutch for most of the team, to never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem.
- mschild 1y agoI think that always depends entirely on the docs and how people are instructed to use them. From a software engineer standpoint, we have a larger collection of docs for the internal platform we run. The docs for other engineers follow the diátaxis framework [0] for documentation. Its the best approach we've found so far and the overall questions and guidance my team needed to provide reduced by a significant margin while the PRs we know receive have increased in quality and quantity. [0] https://diataxis.fr/ https://diataxis.fr/
- throwaway2037 1y agoI think that you are interpreting this outcome as technology-wise negative. Instead, I will offer a commercial positive: If the docs that wrote are so great, then you can hire lower skill, cheaper support staff. Training is also cheaper (because of docs). If I was senior IT mgmt or biz mgmt: That is a win. > never be able to grow in their role and move up to tier 2. I'm not sure how to solve for this problem. I have a selfish answer. Who cares about staff that don't improve. Really. Read that twice. Leave them behind in the dust. I am always blown away when I meet someone in my career and they have been doing some shitty support role, and they have barely progressed (career-wise or tech-knowledge-wise). Who are these people? Everyday, they dig a hole, then a 4PM they fill the hole. Rinse and repeat! Someone who is smart enough to "figure it all out" and write docs should be promoted, or moved to another support team to repeat the same pattern.
- al_borland 1y agoIn the past (20 years ago), those tier 1 roles were a great feeder for the organization. Because that role touched so much, it meant everyone had a lot of perspective on the organization as a whole, and thought about support and maintenance while building new things. It’s easy to say who cares and hire from the outside, but that organizational context and care for support is lost. People build whatever and throw it over the fence, which makes everything worse, imo. Those people also tend not to stick around, so they have no skin in the game and it’s hard to develop culture as people rotate in and out frequently. There are always some people who will never learn, and these people are cheaper, but there are other hidden costs as you seek to optimize for low-skill workers.
- aDyslecticCrow 1y agoOr let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.
- efitz 1y agoWow, way to double down on “I really hate everyone who doesn’t have exactly my skill set and experience.”
- trashymctrash 1y agoI think you are misreading the parent comment here.
- aDyslecticCrow 1y agoI'm ... confused what you mean. If the junior is gonna untangle the docs anyway, why not make them directly update the parts that confused them once they're through it.
- efitz 1y agoI apologize; I misunderstood. I thought you were making a “fend for yourself” argument; I was not associating “junior devs on the team making the docs, need to fix docs or make good ones”.
- turtleyacht 1y agoThey're not necessarily prohibited from asking questions if they're stuck, though. But also search in the chat channels for similar issues. Updating docs in source control also onboards folks to code review. It would be weird to update docs and get a hostile reception. While nice to walk through with someone and conduct a usability study, just leave it better for the next person (who could be yourself, if you forget). That has happened before.
- Lalabadie 1y agoI'm a senior designer who often contributes to front-end code when it's convenient for my client. Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.
- gchamonlive 1y agoI like to always provide a docker image which can be used to execute whatever solution I'm developing. Most of the time the docker image isn't even used, but it's an important exercise because I'm forced to run my solution on a fresh system, so the resulting docs will invariably be more complete, and it also documents the dependencies in a way you can easily verify.
- geocar 1y ago> just watch. You need to be brutal with yourself for this, and understand you're chasing popularity, and not necessarily revenue. It's good to be popular with your users, but if your users are not your customers... > I've used FAANG docs that don't come close to passing the above criteria. ... FAANG is an excellent example of which; Because their documentation and code is so bad integrations always take longer than anyone can estimate, this actually discourages managers from considering a second integration. That is to say it's not necessarily good business to "pass the above criteria" and I think it's important to remember that.
- eviks 1y ago> Especially when using docs for critical tech I only use from time to time (where I forget lots of it). An important point easy to lose sight of when writing when that knowledge isn't lost yet
- simultsop 1y agoWithout AI, it was really hard to get to understand some docs. Today if you don't use AI for these situations shrugs Most cases it is not that docs author forgot users wont have same toolchains. Simply do not bother reducing config files to share just source code. Indirectly pushing users to make use of same tools. Hopefully in 20 years no one will be going to check the source code of anything, and programming is elevated even more. 50 years is crazy amount of time, to stay this primitive. Tech shouldn't just evolve for end users.
- ninetyninenine 1y agoLLMs have mostly eliminated the need for this. They are quite good at explaining things.
- teddyh 1y agoCorrection: They are very good at writing seemingly-good explanations. The explanations may or may not be correct.
- ninetyninenine 1y agoCorrection: They are quite good for this: Easy beginner level stuff. For that specific thing, they are much MORE correct than they are wrong. The status quo is a moving target. 6 months ago what you said would be fully correct. This is no longer the case, now you are only sometimes right and mostly wrong. It is getting better.
- buildsjets 1y ago[flagged]
- ninetyninenine 1y agoDon't like your tone. Please speak in a non offensive way or leave.
- 4pkjai 1y agoWe do this in game development . Watch someone play the game for the first time. Don’t interfere. See if they can figure out how to play.
- bob1029 1y agoPlay testing is the most important part of game development. Indies who struggle to come up with concepts are really sleeping on this. If you run play tests well enough your roadmap will almost write itself. Players will do and ask for things that you would never dream of. I think an intense culture of playtesting is why valve software puts out games so rarely. Their new strategy seems to be to keep a title semi-secret for years while a small army plays it full time. If Deadlock makes it to market, it is almost certainly going to be an acceptable game to most who are even remotely interested in the genre.
- leokennis 1y agoI absolutely love this approach. It is in the spirit of https://1x.engineer/ https://1x.engineer/ and it should be applauded.
- imgabe 1y agoI seem to have this problem a lot with Apple’s docs. So much of it is like Nargflargler: Flargles the narg You need to do something besides repeat the name in the definition.
- wouldbecouldbe 1y agoOr with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens
- whstl 1y ago> with Xcode, go to fargler settings click on narg screen I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game. Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.
- Aaargh20318 1y agoRelated to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this). setFontSize(float): sets the font size. Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).
- bonoboTP 1y agoIn similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.
- CaptainOfCoit 1y agoThat's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is. It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.
- bombcar 1y agoWe called this the “receptionist” test decades ago at the small company I was at - after we though we were done we’d give it all to the receptionist and ask her to use it; and we’d hang our head in shame at everything we forgot and head back. There’s a version for kids to show the details of how to program by literally interpreting steps. https://youtube.com/watch?v=n4rh2jD8OkY https://youtube.com/watch?v=n4rh2jD8OkY
- swiftcoder 1y ago> have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do And if you have access to user experience researchers, go talk to them! They are experts in running this kind of scenario, and can help you avoid all the pitfalls that might bias your results
- angiolillo 1y ago> Do not speak to them, certainly do not help, just watch. Sounds simple, right? I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse. Having a neutral moderator can help as it allows the people who made the UI/docs to stay on mute or on the other side of one-way mirror. But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".
- mschuster91 1y ago> You can also record it to show them later, but for various reasons it doesn't resonate quite as strongly when it's not live. Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing. With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.
- angiolillo 1y agoBefore I saw your response I removed this sentence from my post as I realized it was not central to my main point. However, I still agree with it and am happy to explain why. > wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts First it depends on whether the audience for your product includes people who do not know keyboard shortcuts. If that's not your target audience then the rest of the test may not be valid anyway. Otherwise, there is utility in forcing yourself to watch your users struggle with your product. The best product developers/owners I know have a bottomless appetite for observing people use their product, even if doing so means deferring the rest of their "full backlog of shit". Perhaps they're less efficient in the short term at churning out lines of code, but the understanding and empathy they develop makes them significantly more effective in the long term.
- bonoboTP 1y agoI'll go against the grain and say that fumbling is how you learn. The easier it is to get to the end of the tutorial, the less you learn in the process. If you learn math from a bad book, you have to organize your own notes, to untangle the mess. If it's laid out all neat and clear like a straight highway, you never wrestle it out with the concepts and you don't learn.
- toyg 1y agoThat's something I came to accept as well - deeper understanding will only come from challenge. Unfortunately, there isn't always the opportunity to let people fail, and that opportunity is definitely not in a set of reference docs.
- zahlman 1y ago> and that opportunity is definitely not in a set of reference docs. Okay, but GP is talking about tutorials, which are a completely different form of documentation.
- ctkhn 1y agoIt's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end up writing up a new doc that's good for its point in time, immediately becomes out of date when someone adds a new system or access group but doesn't document it anywhere. The one team I was on previously that got me everything I needed in about two days was great, but it's sad that this isn't the norm. Everywhere else has been pretty hostile to getting set up, and the poor onboarding experience has been a preview of the developer experience. My current role is standing up a new devex team which I'm hoping turns the tide here.
- BossingAround 1y agoIt's not very crazy to me. Most corporate teams are overrun with feature creep that "is very simple" (i.e. it takes 3x as long as estimated, because the codebase is a mixture of overengineered spaghetti for that one customer with edge-case requirements and legacy, combined with tests that are meant to be run in a jenkins job which takes 4h to complete). Then, the engineers are expected to write the docs in between these tickets, and doc is seen as something "to be done within 30 minutes" - of course the docs will be comically (or tragically, depending on your perspective) bad. Most people have 0 idea on how to write good docs, so in 30 minutes, they write stream-of-consciousness docs and return back to the ticket hell.
- ctkhn 1y agoMost places I've been could have been upgraded with stream of consciousness. It's not surprising that they aren't all perfect, and the one place that was done to a very high standard was properly overdone, but at most places whatever counts as onboarding docs either doesn't exist, is essentially unusable, or directs me to legacy things that on day one I don't know enough to not bother with
- underlipton 1y ago
- psygn89 1y agoI always write my own notes when setting up to "fill in the blanks" of the guide, then I create PR with them.
- parpfish 1y agoReading through bad setup docs is 10x more stressful when they are part of new employee onboarding. I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer
- gregates 1y agoMy first ever software developer job, I was hired with basically no knowledge or experience to learn (I was very lucky). I knew MS-DOS command line pretty well from my childhood, but hadn't ever used POSIX. I was given a macbook air and some docs to follow. Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.
- theptip 1y agoI wonder if we now have the tools to build unit tests for docs now; an LLM should be able to take on the persona of a beginner try to follow your doc. For bonus points use a dumber/older model that can’t have trained on your API.
- donkeybeer 1y agoPeople here are talking about it as if its merely a problem of wrong target audience when the problem is a lot of docs are straight up lies. The example setup steps and configuration in the front page itself fails. That's what makes me wish I could shoot someone or something.
- tzs 1y agoDon't speak to them or help them at all? Suppose they get stuck on the first step in a multistep procedure. Do you just let them keep flailing on that step for however long they are available, so all that you learn from that entire session is that the first step needs rewriting? Or do you end the test and let them go, again learning nothing beyond that the documentation for the first step sucks? Wouldn't it be better at that point to help them on to the next step and then continue on having them test the rest of the steps?
- tomatohs 1y agoI started a company to do exactly this a few years ago, and got to work with amazing companies testing their developer experience. The problem is not the docs, it's Conway's law. One team designs the API, the other team designs the portal, and another team designs the SDK. The user has a holistic experience that cuts through each team. That, and the docs are usually written first by the most technical person around, who has a hard time sharing the world view of a noob.
- ElijahLynn 1y agothis works great, if, they speak out their thoughts verbally, in real time.
- mihaaly 1y agoI am stuck in an organization for some personal reasons. The first thing I noticed when I joined was the culture of "Please ask when something is not clear". After was given a quick overview in person. You guess: almost everything is unclear. A mess. Need to ask a lot. Task descriptions, purpose, reasons, whys, wheres, what does this comment mean, why are these things contradict each other, and so on, and so on. And except asking KG, usually the answer is: ask XY. Or KG. People always busy, always in rush, give a condensed answer raising the same amount of new questions that it answers. When KG is out, productivity slows down. And all this beyond the usual in a meeting, out with customer, on holiday, sick, the children is sick, held up in a traffic jam, car broke down, need to finish project P so schedule something for next week, and all those kinds of common things making the relevant person unavailable when "something is not clear". And beyond the forgetting 4 things of the 15 new info given by the time we are finished with the converstaion. No written trail to look back at. When 3 person paint a complete picture then all above happen three times in a row, or in a never ending loop. Productivity suffers, quality suffers, I will leave as soon as I can. Positive things? Probably that the expectations are low. And they pay well. And by now I am irreplecable in a local subset I was hacking together (I do not call it work or development), not even KG can help others there! I will leave on my own terms (as usual, unluckily).
- kazinator 1y ago> If not, note every single place they fail, address each one, and repeat with a new user. Might not this loop be invoking Goodhart's Law? What is "address each one": are we just changing that document, or are we (also) changing something in the system that the document is about? If no newbie has any problem following the document, is that still a good document for non-newbies? If no newbie has any problem with the system that the document is about, are there any downsides?
- timnetworks 1y agoare you interested in giving a talk/presentation about this