A useful setup log starts with the question it can answer
A compact diagnostic record should let someone reproduce a specific observation: state the question, environment, command, exit status, and relevant output. Keep that setup transcript distinct from an inventory of files or storage.
Start with a question
A setup log becomes useful when it answers a question a reader can verify. “Which Python interpreter runs this command?” is narrow enough to investigate. A general dump of terminal history may contain the answer, but it forces the reader to infer which command matters and what result was expected.
A minimal record includes the question, operating system and relevant version context, exact command, exit status, output, and expected result. The supplied diagnostic excerpt is explicitly illustrative: it asks which interpreter runs a command, records a successful status, and shows a path under a project virtual environment. That path is the observation; the expectation explains why it matters.
Record the conditions that affect the answer
Commands depend on their environment. For interpreter selection, record enough to distinguish the active Python installation and shell context: operating system, Python version, working directory, and whether the command was run with an activated environment or an explicit executable path. A command that prints sys.executable identifies the interpreter actually executing it, while a prompt prefix alone does not establish that fact.
A virtual environment sits on top of a base Python installation and has its own executable and package directories. Activation prepends its binary directory to PATH, but activation is not required if the environment's interpreter is invoked directly. Therefore, an environment variable or shell prompt is weaker evidence than the command and executable path themselves. [2]
# Example diagnostic record (illustrative, not a recovered log)
Question: which Python interpreter runs this command?
Command: python -c "import sys; print(sys.executable)"
Exit status: 0
Output: /example/project/.venv/bin/python
Expected: the project virtual environment
Keep the record small and exact
A useful excerpt preserves the command as entered, including arguments and quoting, and reports the exit status separately from output. If the output is long, include the relevant lines and identify what was omitted. Redact credentials, tokens, private hostnames, or user data before sharing; retain enough surrounding structure that the remaining result still answers the question.
For a failure, record the observed error and the expected behavior in plain terms. “Could not install package” is less diagnostic than a command, its nonzero status, and the specific error line. Exactness helps another programmer test one hypothesis at a time instead of guessing at an unseen sequence of setup changes.
A transcript is not an inventory
A setup transcript describes actions and observations in time: a command ran, produced output, and returned a status. A filesystem or storage inventory describes a state at a point in time: paths, devices, sizes, mount points, or other resources. These records answer different questions. A transcript can show how a virtual environment was invoked; it cannot, by itself, establish every file or package installed in it.
Git's diff documentation makes a related distinction for source trees: a diff compares endpoints such as the working tree, index, and a commit, rather than serving as a complete record of every command that produced the state. [1] When diagnosing setup, use an appropriate inventory command for state and a transcript for reproducible actions.
Make the next reproduction cheaper
A concise record should let a reader recreate the relevant conditions without reconstructing an entire machine. Include versions where they can affect behavior, such as the interpreter version and operating system. State assumptions that are easy to miss: current directory, environment activation, and any required configuration, with secrets removed.
Then keep the record aligned to its question. If the question is interpreter selection, the executable path and invocation context are central. If it is package visibility, the import result and environment's package context may matter more. The narrower the question, the less unrelated setup detail a reader must sift through before trying the same observation.