Skip to content

Conversation

@patowen
Copy link
Collaborator

@patowen patowen commented Nov 22, 2025

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:

  • A simple "How to play" whose history is synced with the code would be useful.
  • We get a logical order of what documentation to read, helping to provide an initial understanding to allow the reader to find the relevant code and its documentation for the question they are trying to ask.
  • When we are not limited to code comments, enhanced documentation options, such as diagrams, animations, or potentially even interactive elements could be a possibility.

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.

@patowen patowen requested a review from Ralith November 22, 2025 17:29
@patowen patowen force-pushed the docs-outline branch 2 times, most recently from 98119f9 to 4faedc7 Compare November 24, 2025 16:15
- 'docs/**'
pull_request:
paths-ignore:
- 'docs/**'
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I did this right, future pull requests to this folder will no longer need to run any checks. Assuming this works as I expect, I might do something similar for package.yml in a future PR.

@patowen patowen merged commit f7d0ec1 into Ralith:master Nov 26, 2025
4 checks passed
@patowen patowen deleted the docs-outline branch November 26, 2025 16:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants