List of issues in chronological order
The series of operations before a problem occurs is often the most helpful clue to identifying the problem. Therefore, your instructions should contain the steps of your operation, as well as the reaction of the machine and software, until the problem occurs. In the case of command-line processing, it can be very helpful to provide a transcript of the operation (such as that generated by running a scripting tool), with references to a number of relevant lines (e.g., 20 lines) of the transcript.
Where to start recording
The chronology does not need to start from the day you installed the system. It should start with the "first step that may be relevant to the problem", such as the most recent upgrade, configuration change, dependency installation, data import, command execution, or reboot.
A useful timeline usually contains:
- What you did.
- The system returned something.
- What you then tried.
- Where the problem first appeared.
- After that how do you confirm that it still exists.
The right amount of debugging information
If the program that hangs has diagnostic options (such as the detail switch for -v), try selecting those that add debugging information to the log. Remember that more' is not the same as better'. Try to pick the appropriate level of debugging in order to provide useful information instead of drowning the reader in garbage.
A large, unfiltered section of the log increases the cost of reading it. A better approach is to keep a link or attachment to the full log, while citing the most relevant dozens of lines in the body of the text and explaining why they are important.
Longer questions are summarized first
If your note is long (e.g., more than four paragraphs), it can be helpful to briefly describe the problem at the beginning and then detail it chronologically next. That way hackers will know what to look for when they read your notes.
The summary can be very short, e.g. After upgrading to 2.4.1, importing CSV would report UnicodeDecodeError at step 3; backtracking to 2.3.8 restored it to normal. Here is the full timeline. A beginning like this allows the respondent to establish an overall judgment before going into details.