## Metadata - Author: [[er4hn.info]] - Full Title: Good Docs Take Great Effort - Category: #articles - URL: https://er4hn.info/blog/2023.07.22-good_docs_great_effort/ ## Highlights -  ([View Highlight](https://read.readwise.io/read/01hhfg3tm3xmx7gr3fpcpxgan3)) - The other enemy of technical writers is writing informally. A good technical doc should not have the familiarity of a carnival barker, which is itself a very American saying. The writer should write as though the reader is the defined audience (say, “an engineer familiar with distributed systems”) and not assume any understanding of: ([View Highlight](https://read.readwise.io/read/01hhfg5cf7jkayyde7z2rcnpnf)) - • Sports - No sayings such as “Touchdown!”, “Doing this is a red card move”, “Double header”, etc. • Regional Politics - Avoid anything involving descriptions of your country’s politics because they may not make sense to international readers or offend local ones: “Two semaphores may interact in a way that causes a deadlock. This is similar to when Republicans control the House and Democrats win the Senate.” • Sayings in your country or native language: “This image processing library can detect itsy-bitsy tell-tale signs of funny money without a cashier needing to dilly dally” is not going to make sense to non-native speakers of English. Instead frame it as a more precise “This image processing library can quickly detect signs of counterfeit currency.” • References to the reader: The reader is not a “gentle reader”, is not “going to see it is easy”, and should not be told “You will feel happy with yourself to know these things”. These are technical docs and one should just stick to the facts. ([View Highlight](https://read.readwise.io/read/01hhfg5hh7crdc8n9jwqdv5je2))