At the start of college I was told to keep an engineering journal. I was told to write down problems I encountered and how I solved them in detail. The idea is that you should never have to solve the same problem twice. I will share how I structure my troubleshooting notes, process notes, and concept notes below.

An idea to keep in mind: "Write the article you wish you found when you were trying to solve a problem." When you are making notes ensure they are detailed enough that they can be used by someone with little background knowledge to solve a problem, complete a process, or understand a concept at whatever depth you need.

Troubleshooting Notes

These are simply notes about problems you encounter, with some details about the situation, and ultimately how you solved them. Having a good catalog of these notes will make you better and faster at what you do.

Structure

Date. Problem Description.
Symptoms: Key details or indicators of this problem
Details: Versions this error has been encountered on, environment details
Solution: Troubleshooting information and steps
Notes: Any additional notes about the problem

Example

2017-10-01. Serial Connection Failure.
Symptoms:

• Screen silently closes when establishing a serial connection.
• Proxmarx3 software returns Error: Invalid Serial Connection.

Details: Errors occurred while trying to establish a serial connection from within a chroot on a Chromebook device.
Solution: sudo adduser $USER serial followed by logging out and logging back in.
Notes: Crouton maps groups such as HWaudio, USB, and serial to the coresponding groups in the chroot but does not add users to all of these groups automatically.

Process Notes

These are hard notes to keep but can be some of the best notes to have available. It can be hard to document a process after you have finished it. Your memory may be good, but it is not infallible. If there is a lot of time between when you had to do something last and when you need to do it again, you may forget important details.

Structure

Date. Process/Goal.
Details: What are you trying to accomplish, and why?
Versions: Versions used.
Steps: Detailed step-by-step guide, with diagrams and pictures, of the process from beginning to end.

Testing Your Notes

To test your notes have someone, yourself or another, attempt to complete the process you detail using only your notes as guide. Get feedback and adjust them as necessary. Give yourself time between writing your notes and testing them if you are testing them yourself. If your notes miss key details, you may fill in the gaps without realizing it or assume those details are common knowledge.

Concept Notes

These notes require research and time to complete. For concepts it is important to be clear and detailed, and to write about the concept in your own words with your own understanding. If you simply copy material out of a book it will not have context and will not be helpful. Also be sure to revisit them from time to time to keep them up to date.

Some tips for concept notes:

• Include the date of your original entry, and the date of your last edit
• Use clear, concise language
• Diagrams and flowcharts are your friends
• Cover both theory, and use practical examples to back it up
• Annotate equations with what is happening from step to step

Conclusion

Engineering journals are tough to manage. I have been told that people nowadays tend to remember how to find information rather than the information itself. A well-kept engineering journal will support you for a very long time since you will not have to go far to find solutions to problems when you encounter them for the second time.

Some closing notes: I add troubleshooting and process entries to my paper engineering journal ordered by date. I recognize problems that I have solved before and can approximate where in my book the solution is. I keep my concept notes at the rear of the book as they often require space for revisions and additions.

Support the Author

Devon Taylor (They/Them) is a Canadian network architect, security consultant, and blogger. They have experience developing secure network and active directory implementations in low-budget and low-personnel environments. Their blog offers a unique and detailed perspective on security and game design, and they tweet about technology, security, games, and social issues. You can support their work via Patreon (USD), or directly via ko-fi.