justinmeiners / efficient-programming-with-components

Course notes for Alexander Stepanov's teachings on design and usage of C++ STL.
https://www.jmeiners.com/efficient-programming-with-components/
74 stars 6 forks source link

footnote about identity violation exercise in chapter 3 #21

Closed aharrison24 closed 2 years ago

aharrison24 commented 2 years ago

This is a suggested solution to #14 for the exercise in chapter 3. I think the main thing is just to let readers know that they will be given a solution to the exercise later, so they don't need to be worried if they're unable to solve it.

I also added a new line before the Exercise, so that it appeared on its own line rather than being inline with the previous paragraph.

I did try to put in a relative link to the chapter, but it wasn't clear what the best practice for that was. Something like [chapter 6](./06_min_max.html) works, but hard coding the .html suffix seems a bit icky.

justinmeiners commented 2 years ago

Style options:

  1. Footnote, as illustrated in this PR. "The answer to this exercise is found in chapter X."
  2. Parenthetical. (solved in chapter X).
  3. Additional sentence at the end of the exercise statement: "The answer is found in chapter X."

I think I like 2 or 3 because in a few exercises I provide the solution in a footnote. So, we could tell the reader the solution is in the footnote to give them a chance to solve it before seeing the answer.

It would be really nice if it could link to the other chapter in a way that works in markdown and html, so that we don't have to remember the chapter numbers, but I don't think there is an easy way to do this in markdown.

Do you have any thoughts? I would also like @rpendleton opinion.

aharrison24 commented 2 years ago

Any of the three works for me, with a very slight preference for 2. I agree that 1 is less desirable when some exercises are actually solved in a footnote.

justinmeiners commented 2 years ago

Great, let's do 2.

justinmeiners commented 2 years ago

I have added a file .github/STYLE.md to track these decisions.

aharrison24 commented 2 years ago

Nice! I've updated this PR to follow the shiny new style guide.