3 ms·

Good language documentation requires a collection of skills: * writing * super high empathy * a deep understanding of the language in both substance and form

Good language documentation requires a collection of skills: * writing * super high empathy * a deep understanding of the language in both substance and form * persistence and adversity through a challenging effort Most developers I have worked with the in past struggle in all those bullet points except possibly that last one. Everybody in software likes to think they are awesome, but tell them to write an essay or formal documentation and that confidence is immediately shattered.

janalsncm 2y ago
The empathy part I don’t understand. I don’t even need to write good docs for other people. I can do it for myself in 6 months. Anyone who has looked back at their old code should understand that unless you’re doing something entirely trivial a comment or two will be really useful.
- lifthrasiir 2y ago
  That's often not enough when your audience is much more clueless than you assume. You would have to repeat examples over and over and throw some more just in case.
- acuozzo 2y ago
  > The empathy part I don’t understand. This is what you need when writing documentation covering... 1. Where should someone new to the codebase start? Literally, which line in which file? 2. How does the code "fit together"? What is the call-graph of its top use-cases? 3. What are its compile-time and run-time dependencies? Which exact versions of those dependencies were used during development? 4. When something isn't working, how can someone replicate your development environment EXACTLY in order to determine what's different about theirs? 5. How would you approach debugging on this codebase? A detailed write-up or even a video of every step you took could help someone new gain a deep understanding quickly.
  - janalsncm 2y ago
    Yes, those are the main things I would also probably not remember in 6 months, and tend to write down in a readme.

janalsncm 2y ago

The empathy part I don’t understand. I don’t even need to write good docs for other people. I can do it for myself in 6 months. Anyone who has looked back at their old code should understand that unless you’re doing something entirely trivial a comment or two will be really useful.

lifthrasiir 2y ago
That's often not enough when your audience is much more clueless than you assume. You would have to repeat examples over and over and throw some more just in case.
acuozzo 2y ago
> The empathy part I don’t understand. This is what you need when writing documentation covering... 1. Where should someone new to the codebase start? Literally, which line in which file? 2. How does the code "fit together"? What is the call-graph of its top use-cases? 3. What are its compile-time and run-time dependencies? Which exact versions of those dependencies were used during development? 4. When something isn't working, how can someone replicate your development environment EXACTLY in order to determine what's different about theirs? 5. How would you approach debugging on this codebase? A detailed write-up or even a video of every step you took could help someone new gain a deep understanding quickly.
- janalsncm 2y ago
  Yes, those are the main things I would also probably not remember in 6 months, and tend to write down in a readme.