2 ms·
1. Linear reading: define things before talking about them. 2. Make documentation explicit, not implicit: no acronyms or assuming context. 3. No marketing or
by 29athrowaway 4y ago
1. Linear reading: define things before talking about them.
2. Make documentation explicit, not implicit: no acronyms or assuming context.
3. No marketing or self-promotion: your code is not fast, efficient, reliable, convenient or secure because you say so.
4. No ego: nobody has time to read about you or a story from your life. Keep that to your blog.
5. No humor: if it's 3 AM and you are debugging a problem, and you are being forced to read lame jokes to understand what some code does, you are going to get frustrated as hell.
6. Punctuation, grammar, orthography.
7. No aggression: Nobody has time to read rants as they're trying to work on code.
8. Prefer simple English, leave local idioms and slang aside.
9. Conciseness.
- jacobyoder 4y ago> your code is not fast, efficient, reliable, convenient or secure because you say so. I often would be in meetings where tech folks would introduce their code (to non-technical audiences sometimes) as 'tight' or 'super fast' or... similar. It was cringey every time, and... often wrong. Yay - you got a query down from 8 seconds to 2 seconds. That's not really 'super fast' though - with a bit more work (or experience) that would be 300ms or less (which I eventually did with about 30 more min of rewrite and indexes).
- nicbou 4y ago10. Structure. Make it easy to find the relevant section and jump to it. Chances are you don't need to read content start to finish.
- 29athrowaway 4y agoOh yes, good point. And format... Format code as code, text as text, math as math.