Add outline for detailed documentation #459
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The Hypermine code base has become large enough that it is not always clear where a new potential contributor should start. It's also easy for existing contributors (like me) to have to relearn parts of the code that we are less familiar with.
I believe this project would benefit from some kind of documentation outside the main codebase (but still managed by pull requests). Such documentation would have the following benefits:
I have not yet worked out the logistics of including diagrams etc. in the documentation yet. For documentation maintainability and for keeping the repo size down (to avoid running into limits), none of these diagrams should be checked into source control. Instead, code that can generate these diagrams consistently should be included instead. I am interested in suggestions on which graphics APIs such code should use (or if there are other ideas on how to handle this problem in general).
Note that this PR just adds the outline for the documentation, along with ideas and suggestions on how it should be written. While all this information could live in a GitHub issue, I believe this PR format makes it easier to discuss, and having the outline in the repo itself makes it easier to track changes to these plans in general. One downside is that CI runs unnecessarily. It might be possible to configure it not to do this.