Groom project documentation

[hollasch]

Review README.md, CONTRIBUTING.md and the wiki. For example, the README needs more project information, some of which is currently located in the wiki.

[hollasch]

Add a blurb about the role of the development versus master branches.

[hollasch]

On rethinking this, we should add additional notes in the repo directly. The entire project should be usable and complete in an entirely offline mode.

That means either an appendix covering platform-dependent issues, or standalone notes in a notes/ directory or something.

Anyway, needs more overall thought.

[hollasch]

Removing the punt label. This should be resolved in the v3 release.

[hollasch]

Consider a section on further reading, such as Ray Tracing Gems. Probably start out as a seed wiki page.

[trevordblack]

Do we want a Further Reading section as a ...

• markdown page in the root directory
• markdeep html document in root
• written into index.html

I personally quite like the idea of a further reading markdeep document that is referenced as is it's own section in index.html

It isn't unreasonable to see such a thing quickly becoming the de-facto source for extended Ray Tracing learning

[hollasch]

I think a standalone Markdeep document in the books directory would be best, and we can also link to this from the web home page (index.html). Initial form isn't important, but I imagine that it would evolve into bibliography, perhaps categorized by topic. In fact, it might even be called bibliography.html. Sections should be addressable, as should individual entries.

[trevordblack]

Okay, I have a bit of a jumbled mess where you'd typically find a brain.

For the FurtherReading.html (or Bibliography.html, I prefer FurtherReading.html in the first draft), how do we want to structure it?

From the wiki: https://github.com/RayTracing/raytracing.github.io/wiki/Aggregation-of-Possible-Next-Steps

We have a couple of dissimilar things jumbled together.

1. LOCATIONS of content
   • Chapters in the books
   • Blogs from the in1weekend blog spots
2. TYPES of content
   • External resources
   • Possible next steps (exercises)
     • Some are found in the next book
     • Some are not found in the next book

This is biting off more than we can chew, but, for my own sanity, at least,
I would like the project to get to a place that,

1. Overhaul of all the "Next Steps" chapters in the book.
   • One chapter at the end of each book
   • This chapter has
     • brief overview of topics covered in the next book
     • Possible exercises that are not covered in the next book
     • (don't mention topics from 2+ books on)
2. The FurtherReading.html doc contains
   • No exercises
   • External resources for every chapter in the books
   • An Assumed Knowledge section covering the basics (math, programming)
   • A Common section for resources that are relevant to multiple books, chapters
   • An Extension section for resources that are the next places to learn
   • (Maybe) An Unsolved Research Problems section for state-of-the-art resources/questions

This is explicitly not a text book, but at some point we might need to have a conversation about Exercises. The books already nod toward having them (in the Further Reading sections), but the explicit outlining of Exercises introduces a lot of friction for the reader.

Indeed, all of the structure outlined above is an increase in friction for the reader. So I don't strongly recommend any of it, but it's a topic I've been ruminating on for a few weeks, and have largely not had any success in congealing. The excessive structure is simply a coping mechanism.

[trevordblack]

Consider pushing to a 3.2

[trevordblack]

This issue is kind of 2 different things at this point

1. Overhaul of README.md, CONTRIBUTING.md and the wiki. Including outlining roles of different branches
2. Outlining a further reading document

For the second part, #407 is maintaing that.

Is the first part completed? We might be able to close out this issue?

[hollasch]

The issue is fuzzier than I'd like. I was thinking of OS/platform/IDE specific guidance and supplementary documentation like that. I suppose that's backwards, and we should wait until we have some actual content first and then figure out how to fit it in.

[trevordblack]

TheNextWeek:Overview

What I will do in this mini-book is go with the simplest approach
in each design decision I make. Check https://in1weekend.blogspot.com/
for readings and references to a more sophisticated approach.

This will eventually need to be changed to point to the documentation outlined here

[trevordblack]

I lied. This thing is 3 issues.

1. Overhaul of README.md, CONTRIBUTING.md and the wiki. Including outlining roles of different branches
2. Outlining a further reading document
3. OS/platform/IDE specific guidance and supplementary documentation like that

I'm going to unassign myself and have you (@hollasch) do numbers 1 and 3. We're definitely punting on 2.

I think we need to do 1 (overhaul of ...) for v4, the question is if you want to punt on 3.

[hollasch]

Yes. OS/platform/IDE specific guidance has been added ad hoc inline where necessary, and we don't really hit enough of these issues to warrant a more formalized solution.

So this is just scoping down to a light overhaul, and probably doesn't even really need further work outside of talking about the latest release status.

[hollasch]

Done in master. Time for this spaghetti monster to go move along.