undefined | Better HN

0 pointsChaebixi8y ago0 comments

How do you express "X is a dead end; we tried it and it didn't work because Y, so this is Z" as a unit test? The strength of prose is that it can be used express concepts with an efficiency and fluency that syntactically-correct cannot do.

Sometimes you just have to pick the right tool for the job, and sometimes that tool is prose. I think if you get too stuck on using one tool (e.g. unit tests), you sometimes get to the point where you start thinking that anything that can't be done with that tool isn't worth doing, which is also wrong.

0 comments

harlanji8y ago

Literate commit messages. The tool TRAC did a great job of surfacing project activity into timelines and exposing views like that. It's possible with GH but I'm usually the only one on projects to write commit messages that aren't dismissive like "words" or "fdsafdasfas"... soooo.... Release Notes are the best I can do for now.

Bigger still, is what happens when a project spills beyond a single repo, but not even Google is that big :) :). Apache projects are good models for that kind of documentation IMO, even though the pages have ugly css.

the_af8y ago

> Literate commit messages.

That's a form of written-in-prose documentation like the OP was arguing for, and unlike writing unit tests. Documentation doesn't have to be in a separate file.

j / k navigate · click thread line to collapse