> ## Documentation Index > Fetch the complete documentation index at: https://docs.pebchip.top/docs/llms.txt > Use this file to discover all available pages before exploring further. # Lightweight Technical Note Template for Engineers > A structured 7-section note-taking template to help engineers understand, retain, and communicate technical concepts effectively and consistently. 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 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. 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. 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. 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. 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. 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. 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. ```markdown Filled-in note theme={null} ## 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.