Documentation improvements

[sharkdp]

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.
• Add the step-by-step guide from Complete collection of syntax highlighting test files #1213 to https://github.com/sharkdp/bat/blob/master/doc/assets.md as a requirement for the addition of new syntaxes.
• Update the man page to be up-to-date with the --help text.

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.

[trncb]

@sharkdp if no-one has taken it, I can find a way to integrate assets/README.md into README.md

[sharkdp]

@sharkdp if no-one has taken it one, I can find a way to integrate assets/README.md into README.md

I don't think anyone has 👍. I think it would be best to move assets/README.md to doc/assets.md and then write a short section in the README.md that links to this document. It might also be a good idea to review assets.md for possible improvements/updates.

Later, I would also like to extend doc/assets.md to describe the whole process of getting a new syntax accepted in bat (including the policies, for example: #1262).

[trncb]

Good thinking. I'll take a stab at it.

[asamant]

@sharkdp Having a CONTRIBUTING.md file with instructions for new developers would be of much help to address the issue regarding the CHANGELOG.md file update. So the README.md file can be from a user's perspective and the CONTRIBUTING.md file from a developer's. Thoughts on this?

[sharkdp]

@asamant Yes - absolutely. We are planning to create a CONTRIBUTING.md file soon that would have this changelog step as one of the main entries.

[adrian-rivera]

I added a new section Contributors on README to address the missing item on the TODO, please take a look!

[sharkdp]

Closing this for now, as all tasks have been resolved and the remaining documentation tickets are tracked in the v0.18 milestone.