Add a philosophy document to exercises directories?

[kytrinyx]

In #375 (comment) @petertseng says:

these things should be documented so that we can avoid duplication of past efforts.

How about if we create a file in the exercise subdirectory that documents our discussions and efforts?

We wouldn't need to add this to all exercises, nor all at once. But as we have discussions it would be incredibly useful to be able to have the results of these discussions on hand.

[petertseng]

I also suggest that it could be put in the canonical-data.json (if it should be mainly targeted at track maintaineres), or the description.md (if it should be targeted at students)\

to reuse existing files and not introduce a new one

[kytrinyx]

I'd rather keep this out of the description.md since this is about why we ended up making the choices we did, or which trade-offs we considered and then rejected.

This also feels different from canonical-data.json as well, as that feels like it is the end result of the discussion, and most people who want to use it to generate a new implementation should be able to follow it without worrying about the details, unless they're interested in them.

[jtigger]

I really like this idea. I've seen the same on long-lived systems and been grateful for the insight on why certain design choices were made. Knowing why can really make work more efficient: it increases my confidence that I'm making "good" changes and has saved me from repeating history.

The most useful ones I've seen have a simple formats, something like:

1. Overall context (where idea came from, original problem being solved).
2. Key Descision X:
   • Problem/Aspect
   • Decision (expected benefits + known trade-offs)
   • Other options considered (terse, but some hint as to why deemed unsuitable)

The latest iteration of such documents I was involved in for a system were deliberately and specifically version controlled so that text could be safely deleted without fully losing that history.

Is this the kind of thing you're talking about @kytrinyx?

[kytrinyx]

Is this the kind of thing you're talking about?

Yes, that's exactly it.