4 ms·
This is why I also didn't particularly enjoy answering questions concisely at my previous company. I still did, I just hated it. Documentation can describe a s
by hnick 4y ago
This is why I also didn't particularly enjoy answering questions concisely at my previous company. I still did, I just hated it.
Documentation can describe a system state, and how to use or approach it, but in my experience it really lacks in capturing the full depth of experience when it comes to interacting with it. All the little shortcuts and workarounds. All the debugging steps. Seeing something, and realising you've seen it before and solving it in 5 minutes instead of the entire day it took you last time. I could write a story about that day, but it wouldn't do anyone any good - they won't learn from that experience like I did and it won't spring to mind instantly. Assuming they even know where to find a piece written about their specific problem.
So when someone says "How do I X?" all I can think about is all the incidental things I've learned when trying to do something else. This builds the bigger picture. I can answer your question, but you'll just paste the code in and be back to ask more tomorrow. I valued the coworkers who treated such things as more of a discussion and learning opportunity than a transactional question-answer routine.
- perrygeo 4y ago> the full depth of experience when it comes to interacting with it. This is the part that most people conveniently forget. Many people find it easier to create elaborate docs and processes than to regularly interact with the software system they've built.
- deleted 4y ago[deleted]
- aorloff 4y agoThis is why effective documentation starts with run books.
- malandrew 4y agoI have a love-hate relationship with runbooks. I see them as tech debt for things you haven’t yet automated or made clear enough. If someone needs to go read a doc to understand what they need to do, you’re already behind.
- PebblesRox 4y agoI can't find it now but I remember reading a post on HN with the suggestion to make all your runbooks shell scripts, even if all they start out as a series of prompts walking the user through the checklist of manual tasks. This way you can incrementally automate various pieces of it so that gradually the user is doing less and less, but there's continuity on their end: run the script and do whatever it says to do next.
- TheFlyingFish 4y agoI'm guessing this is "Do-nothing scripting: The key to gradual automation" https://news.ycombinator.com/item?id=29083367 https://news.ycombinator.com/item?id=29083367 Although the example uses Python, rather than shell.
- PebblesRox 4y agoThat’s it, thank you!
- dougsillars 4y agoI love this idea! The automate the easy bits (or the steps that are the biggest pain/time suck) until the whole thing is completed. A tool like Jupyter Notebooks would be great for this - comments & code can be placed into a single document. I'm working on a project called unSkript (https://unskript.com https://unskript.com) that is built on this idea.