Clear technical explanations

Technical writing should let someone understand a system without guessing which version, input or environment the author assumed. Begin with the question the reader is trying to answer, then present a small correct example and only the details needed to explain it.

Improve vague statements

Vague: “Binary search is faster.”

Useful: “On an already sorted array, binary search performs O(log n) comparisons in the worst case. It requires random access and does not include the cost of sorting the input first.”

Vague: “Use Git to update your branch.”

Useful: “Check the current branch and uncommitted changes with git status. Fetch the remote, then merge or fast-forward the intended default branch according to the team workflow.”

Good explanations name their assumptions, define their input and separate an asymptotic claim from benchmark observations.

Keep each page focused

Use headings to allow scanning: purpose, prerequisites, mechanism, example, trade-offs, verification and related reading. A reference page may favor tables and exact signatures; a tutorial may favor worked steps. Avoid repeating generic theory on every page when a central overview can explain it once.

Write for maintainers

Specify the behavior that can be verified, not only an opinion that something is “better”. For state-changing instructions, include a safe validation step and note rollback or recovery when appropriate. Never publish sensitive infrastructure details in public docs.

Exercise: Rewrite “this code is optimized” into a measurable claim. What was measured, with which input, and under what conditions?

Continue with Markdown and README files.