Always define technical terms and concepts explicitly in documentation rather than assuming reader knowledge. Avoid ambiguous phrasing that could be interpreted multiple ways.
Always define technical terms and concepts explicitly in documentation rather than assuming reader knowledge. Avoid ambiguous phrasing that could be interpreted multiple ways.
When introducing technical terms:
Examples of good practice:
# Good: Clear definition
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit
description that are formatted as `<key>: <value>`.
# Bad: Ambiguous phrasing
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit
description, formatted as `<key>: <value>`.
# Good: Precise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all tracked remotes.
# Bad: Imprecise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all remotes.
This prevents confusion, reduces the need for readers to maintain external references, and ensures documentation is self-sufficient. Pay special attention to terms that may have different meanings in different contexts or tools.
Enter the URL of a public GitHub repository