The document discusses best practices for software developers in maintaining lab notes, emphasizing the importance of concise documentation and clarity in work. It highlights the benefits of keeping detailed records, such as easier task resumption and effective team collaboration. Additionally, it offers tips for note-taking and suggests resources for further information on the topic.

1. @jammycakes
Keeping lab notes as a software
developer
James McKay

2. “Prefer working software over comprehensive documentation”
The Agile Manifesto

3. “If it hurts, do it
more often”
Martin Fowler

4. Layered architecture
aka “baklava code”

5. How many places do I
have to change to add a
column to the database?
✤ Entity Framework models
✤ Repository
✤ Service
✤ Business models
✤ DTOs
✤ ViewModels
✤ Views
✤ Tests
✤ Angular.js services, factories,
providers
✤ ServiceFactoryProviderProviders
✤ You have ruined JavaScript!

6. “What did I do
last time?”

7. You may also have asked…
✤ I’ve had this problem before, what did I do to solve it?
✤ What have I already tried attempting to fix this?
✤ I’ve just been brought onto this project, what does it
do and how is it structured?
✤ Why is this code designed the way that it is?

8. My approach

9. Treat it likeTDD
✤ Think about what you’re going
to do
✤ Write down what you’re going
to do
✤ Then do it
✤ Then write down the outcome
✤ Lather, rinse, repeat!

10. Example
✤ https://github.com/jammycakes/terraform/wiki/
issue_9589

11. Benefits
✤ Documentation becomes easier
✤ Clarity of thought to your work
✤ Easier to come back to a task that’s been on hold for a
few days
✤ Easier to hand over to other team members
✤ An audit trail if things go wrong

13. Tips
✤ Use the most low friction
solution that you can
✤ Write down what you’re going
to do before you do it
✤ Phrase it as “I did this…”
✤ Make your notes append-only
✤ Refer back to them!

14. You cannot be
too detailed
✤ Record all command line
instructions that you run
✤ Record the output, but edit for
clarity if appropriate
✤ Learn from your mistakes!

15. Teamwork
✤ When pair programming, one
of you writes code, the other
writes notes
✤ Share your notes with the
whole team
✤ DON’T make them public.
They may contain security
sensitive information.

16. For further information
✤ https://jamesmckay.net/tag/lab-notes
✤ http://www.phy.cam.ac.uk/students/teaching/
teachingfiles/keepnotes-08.pdf
✤ Or search Google for “how to keep lab notes”