Boston Python runs weekly office hours, and I noticed the discussions there often start from a familiar point: how do I get my Python environment to work?
This is a question that recurs in any Python support arena. Python has gotten a lot of heat for environment complexity, but that complexity is due to a number of factors, none of them bad on their own: Python has been around for a long time, it’s used in many different ways, it lends itself to experimentation with tooling, and so on.
I don’t want to gripe about the complexity, and I don’t have a proposal for how to reduce the complexity. What I would like is a resource that people can use to find their way through the complexity.
I’m imagining a self-guided tour that would ask questions about what the user needs, and would bring them to pages with solutions. It would be similar to a Choose Your Own Adventure, but for Python environments. I’ve even started toying with tooling that could produce pages like that.
But there are a number of possible questions that people could be starting with:
- How do I install Python?
- How do I install modules to use?
- How do I package my code for distribution?
Answering any of these well requires finding out details from the user:
- What domain are you working in?
- What kind of expertise do you already have?
- How deeply do you want to be involved in the decisions?
And then more technical details:
- What operating system?
- What shell do you use, if any?
- What editor/IDE do you use?
- What version of Python?
and most of these might be answered with, “I don’t know, can you tell me which to use?” which just leads to more attempts to educate and explain complexities that to the user feel like distracting confusing trivia.
Even harder is the question, “I tried to do it myself, but it’s not working, how do I fix it?” Untangling that requires forensics and details, then education about the inner workings of things and how they got mis-configured.
As tempting as it is to try to capture all of the possibilities and solutions in a flow chart or adventure game, it’s almost certainly impossible to solve most peoples’ problems.
Has anyone seen examples of instructional materials organized in a decision tree like this? Not even about Python, but about anything? I feel like this is impossible, but if it could make a dent in the difficulties people are having, it could be very valuable. I can’t quite get the idea out of my head, and I can’t make a serious start on it.
What can I look at to learn from? Not learn about Python environments, but learn how to construct self-guided decision tree materials?
Update: Dennis Dawson reminded me that I previously blogged about On undoing, fixing, or removing commits in git, which has been updated to be more dynamic at Git Fix Um. These are a good example of the kinds of thing I am looking for.
More update: I got some more suggestions of examples of this sort of thing. SmartBear Online Troubleshooter is a classic wizard flow. There are a few for installation instructions:
More: Veracode cheatsheet and PyTorch Get Started.
Comments
Talking of decision trees, I’d love to have a way for python to tell me why it picked a certain module from a certain path. Like “which” extended to actually explain why it looked up this or that directory. Maybe it exists already…?
Add a comment: