Re:Theory-building and why employee churn is lethal to softw...
by aorloff on Wednesday January 11, 2023 @12:55AM
(#34335481)
This is why effective documentation starts with run books.
Re:Theory-building and why employee churn is lethal to softw...
by malandrew on Wednesday January 11, 2023 @01:31AM
(#34335720)
I 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.
Re:Theory-building and why employee churn is lethal to softw...
by PebblesRox on Wednesday January 11, 2023 @08:33AM
(#34338198)
I 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.
Re:Theory-building and why employee churn is lethal to softw...
by TheFlyingFish on Wednesday January 11, 2023 @12:49PM
(#34341675)
I'm guessing this is "Do-nothing scripting: The key to gradual automation" https://news.ycombinator.com/item?id=29083367
Although the example uses Python, rather than shell.
Re:Theory-building and why employee churn is lethal to softw...
by PebblesRox on Wednesday January 11, 2023 @01:40PM
(#34342537)
That’s it, thank you!
Re:Theory-building and why employee churn is lethal to softw...
by dougsillars on Wednesday January 11, 2023 @02:09PM
(#34343013)
I 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) that is built on this idea.
Re:Theory-building and why employee churn is lethal to softw...
by perrygeo on Thursday January 12, 2023 @08:30PM
(#34362842)
> 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.
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.