Consider using other tools for GitHub issues that aren't tasks or bugs
toolness opened this issue · comments
I've noticed that some of our issues, like #50, #110, #124, and #125, aren't really tasks, but rather documentation or starting points for open-ended conversations.
GitHub issues can be used in a lot of different ways, and one of my "litmus tests" for something that makes a good issue is asking whether it represents either a task that needs to be done, or a bug that should be fixed, or perhaps the start of a conversation that could quickly lead to a task. In short, it should be something that can eventually be marked as "done" and closed. For more open-ended matters and for documentation, I think it might make more sense to use a different tool.
GitHub provides a few tools that we might consider using:
-
GitHub Discussions is essentially a built-in forum for a repository. It could be a good candidate for open-ended conversations like #125, and possibly even for documentation like #124. I've never actually used it, so I'm not sure. There's a Quickstart for GitHub Discussions with more details, though.
-
A GitHub Wiki is built-in to every project on GitHub. This could be great for documentation, but it's not so great for discussions. For more details, see About wikis. And for an example of an existing GitHub wiki, see the p5.js wiki.
-
Finally, we could also put documentation in the repository itself, e.g. in a
docs/directory. The documentation could just be markdown files with associated images; however, embedding images in the documentation won't be as easy as drag-and-drop--contributors would have to add any images to the repository and manually add<img>tags to them in Markdown files with appropriatesrcattributes. While it's not as easy to use, it would be synchronized with the state of the codebase, which can be a good thing, depending on what's being documented.
Thanks @ninapaley! Since we're using discussions now, I'll go ahead and close this issue.