With all the recent news about Hacktoberfest I thought it would be a good idea to point out good beginner issues that would be actually helpful for bat. In the past years, I have actually experienced Hacktoberfest as a really great event - both as a contributor as well as a maintainer.

One thing that I would like to focus on for the next bat release is documentation. This includes the README, the man page as well as the bat -h and bat --help texts. It also includes documentation for contributors/developers like the issue templates.

In my mind, excellent documentation is something that separates good projects from really great ones. A lot of the issues that are opened in the bat repository could have been prevented if the documentation would have been clearer. And for each such issue, there are probably several more users that are already too frustrated with the tool and don't even bother opening a ticket on GitHub.

We can list potential TODOs here, but there is also a list of open issues that deal with documentation which an be found here:

List of documentation-labeled issues.

Apart from that, a few things that come to my mind:

• I think we should merge the assets/README.md file into the main README.md or maybe link to it from the main README. In general, the whole process around contributing new syntaxes (or themes) should be described in detail. Note that there is some information regarding this (policies) in the issue templates as well.
• For contributors, we should clearly document that they should please update the CHANGELOG.md file as well. This makes the release of new bat versions much easier.
• The short bat -h text should refer to the longer and more detailed bat --help text (and vice versa). See my fd project as an example for how this can be done with clap.

If you have ideas on how to improve the documentation, please post them here or open a new issue if it's a larger scale change.