Skip to main content
When you encounter a technical concept worth remembering — a subtle bug, a design trade-off, a system behavior you had to dig to understand — writing it down is only useful if you write it down well. This template gives you a consistent seven-section structure that forces you to move from “I saw this happen” to “I understand why it happens and know what to do about it.” Each section has a specific job: together they turn a raw observation into a reusable, shareable note you can actually review before an interview or send to a teammate. Keep each note to one or two pages. One note per concept. The goal is a growing library of focused, high-quality references — not a dump of everything you have ever read.

​
The seven sections

1

Title

Write a short title that lets anyone — including you six months from now — immediately understand what the note is about. Use noun phrases that name the specific concept, not vague labels.What to write: A phrase that identifies both the topic and the angle. Include the technology name and the specific behavior or decision you are documenting.Examples:
  • LocalDateTime precision issues and alternatives
  • Reliable unlock strategies for distributed locks
  • Why singleflight prevents cache stampede but needs TTL
Avoid titles like “Redis notes” or “Java stuff” — these are impossible to scan when your library grows.
2

Background / Problem

Explain why you are writing this note. Describe the scenario where this problem or concept appeared. This section answers: “Why does this matter, and in what context does it come up?”What to write: One to three sentences describing the real situation that prompted the research. Be specific about the system, the task, and what surprised you or was unclear.Example: During export task processing, you used LocalDateTime for time comparisons and noticed occasional incorrect orderings in the results. You suspected the issue was related to nanosecond precision, which led you to investigate how LocalDateTime handles time internally.This section is what makes your note useful to others. Without it, the solution has no context.
3

Phenomenon / Case reproduction

Show the problem concretely — with a code snippet, a log excerpt, or a minimal reproduction case. This section answers: “What does the broken or surprising behavior actually look like?”What to write: The smallest possible code or log that demonstrates the issue. Do not explain here — just show.If you cannot reproduce it in a snippet, describe the exact conditions under which you observed the behavior.
4

Principle analysis

Explain the root cause. This is the most important section. It answers: “Why does this happen?”What to write: The underlying mechanism that causes the behavior. Reference source code, official documentation, or a logical explanation of the system’s internals. Use diagrams or flowcharts when the causation is hard to express in words.Explaining the root cause — not just “here is the fix” — is what separates a note you can reason from from one you just follow blindly. It is also what interviewers probe for when they ask follow-up questions.
5

Solution comparison

Present the available solutions or alternatives side by side. This section answers: “What are the options, and when should you use each one?”What to write: A table with columns for the approach, its advantages, its disadvantages, and its appropriate use case. Include at least two options so the comparison is meaningful.Presenting trade-offs rather than a single answer reflects how engineering decisions actually work. It also prepares you to answer “why did you choose this approach?” in an interview.
6

Practical advice

Give concrete, experience-grounded guidance. This section answers: “What should you actually do in practice?”What to write: A short bulleted list of rules of thumb, conventions, or guardrails derived from the principle analysis and solution comparison. These should be specific enough to follow without re-reading the whole note.Example:
  • Use a single time type consistently across your service. Do not mix LocalDateTime and Instant in the same domain model.
  • Emit log timestamps in UTC with ISO 8601 format so they are unambiguous across time zones.
7

References + one-line summary

List your sources, then write one sentence that captures the entire note.References: Link to official documentation, the relevant source code, Stack Overflow threads, or articles. This lets you re-verify the information later and gives readers a way to go deeper.One-line summary: Write a single sentence that acts as a memory anchor — something you could say aloud to a colleague in a hallway conversation to convey the key insight. Frame it as a rule or a finding.Example: LocalDateTime is not appropriate for high-precision time comparison; use Instant instead.

​
Filled-in example: LocalDateTime precision

The following is a complete note using the template, based on a real Java time precision issue. 
## LocalDateTime precision issues and alternatives

---

### Background / Problem

During export task processing, you used `LocalDateTime` for sorting
and comparing timestamps. Results occasionally appeared in the wrong
order. Investigation pointed to nanosecond-level precision rounding
as the likely cause.

---

### Phenomenon / Case reproduction

LocalDateTime t1 = LocalDateTime.now();
Thread.sleep(1);
LocalDateTime t2 = LocalDateTime.now();
System.out.println(t2.isAfter(t1)); // sometimes prints false

---

### Principle analysis

`LocalDateTime` carries no time zone information. Under the hood, it
converts `System.currentTimeMillis()` to nanoseconds, but rounding
errors in that conversion mean nanosecond- and microsecond-level
comparisons are unreliable. Two calls to `LocalDateTime.now()` made
1 ms apart can produce values that compare as equal or even reversed
depending on the JVM and underlying clock resolution.

---

### Solution comparison

| Approach                       | Pros                              | Cons                        | Use case              |
|-------------------------------|-----------------------------------|-----------------------------|-----------------------|
| `Instant.now()`               | High precision, time-zone-neutral | Detached from business TZ   | Timestamp comparison  |
| `System.currentTimeMillis()`  | Simple, fast                      | Millisecond precision only  | Performance counters  |
| `LocalDateTime` (current)     | Human-readable, TZ-aware display  | Unreliable for comparison   | Display only          |

---

### Practical advice

- Use one time type consistently. Do not mix `LocalDateTime` and
  `Instant` in the same domain model or service boundary.
- Log timestamps in UTC with ISO 8601 format so they are unambiguous
  across time zones and deployments.
- Reserve `LocalDateTime` for display or user-facing fields where a
  specific time zone is known and comparison precision does not matter.

---

### References

- Java Time API: https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html
- Stack Overflow: "Why LocalDateTime precision varies across JVMs"

---

### One-line summary

`LocalDateTime` is not suitable for high-precision time comparison —
use `Instant` for reliable ordering.
Best practices for using this template
  • Write the one-line summary first. If you cannot summarize the concept in one sentence, you do not fully understand it yet — that is useful feedback.
  • Fill in the phenomenon section with real code or logs whenever possible. Contrived examples are harder to recall than real ones.
  • Do not skip the principle analysis. “Use Instant instead of LocalDateTime” is easy to forget. “LocalDateTime uses a nanosecond conversion with rounding errors” sticks.
  • Keep notes short. If a note is growing past two pages, split it into two notes. Each note should capture exactly one insight.
  • Review notes before interviews. The one-line summary in each note is designed to be a fast recall trigger — scan those summaries to spot gaps and refresh your memory efficiently.