Documentation #1

khinsen commented 2026年02月12日 14:53:35 +01:00

7eb7f3d278 raises a general question about documentation to which I have no good answer.

For anyone who is familiar with Common Lisp, this statement is obvious. It's about the same level of utility as "Program execution will stop at a syntax error".

But neither of these two statements is obvious to someone unfamiliar with Common Lisp. The question thus is what audience to aim for. Provide enough info for newcomers, without drowning the relevant bits in generalities for the expert.

https://codeberg.org/rgb/hyperdoc/commit/7eb7f3d27827efec78a79977d24220cdfc1660b1 raises a general question about documentation to which I have no good answer. For anyone who is familiar with Common Lisp, this statement is obvious. It's about the same level of utility as "Program execution will stop at a syntax error". But neither of these two statements is obvious to someone unfamiliar with Common Lisp. The question thus is what audience to aim for. Provide enough info for newcomers, without drowning the relevant bits in generalities for the expert.

rgb commented 2026年02月12日 19:05:22 +01:00

Thanks @khinsen , I am trying to gather (and provide) enough info for newcomers like me.

Thanks @khinsen , I am trying to gather (and provide) enough info for newcomers like me.