CRAVEX-Docs: Create guidelines for README Files

[tsteenbe]

Create a standardized structure for README files across AboutCode projects, aligning with community best practices. By developing a consistent format, we can enhance clarity, improve user onboarding, and ensure that essential information is easily accessible.

[tsteenbe]

@DennisClark Have a look at

• https://gitlab.com/tgdp/templates/-/blob/main/readme/template_readme.md
• https://www.makeareadme.com/
• https://gist.github.com/PurpleBooth/109311bb0361f32d87a2

[mjherzog]

@tsteenbe @DennisClark I think that we need at least two README templates because of the large difference in scale between our projects. One of the templates like from Good Docs project is probably fine for a small project like license-expression, but we need something different for big projects like scancode.io. We can probably use the same overall structure but some topics like installation are complex/long for big projects and should be covered as links to the RTD or possibly a separate README-install file.
Also I suggest that the README file and similar files at the top-level of the repo should be markdown instead of rST because that makes them easier to edit. We are not consistent across projects atm.

[DennisClark]

@mjherzog I have extracted what I think is appropriate from the examples that @tsteenbe provided for a README template, primarily the one at https://gist.github.com/PurpleBooth/109311bb0361f32d87a2 which is in markdown format, and I tend to agree with you about markdown vs rst for readme files.

I have created a new branch in SCTK for the new README.
See https://github.com/aboutcode-org/scancode-toolkit/tree/new-readme

It's very much a work-in-progress. I had to rename it from README.rst to README.md to get my stuff to format correctly. That's fine, but some older stuff is in somewhat advanced .rst syntax and still needs work.

And, of course, regarding my suggested content: I have tried to avoid duplication of content between the README and the RTD, and took a dramatically different approach to the beginning of the README. It still needs some tuning, but the main objective at the beginning of the doc is to avoid noise, tangents, distractions, etc.

Suggestions and improvements are welcome of course. @tsteenbe and I plan to do a progress checkpoint tomorrow.

[mjherzog]

@DennisClark Thank you for getting this started. We have done a bit of rST to markdown work for purl-spec so we may be able to suggest a tool to help with reformatting the tables and links.
Also we need to factor in advice from https://fosdem.org/2025/schedule/event/fosdem-2025-4990-how-to-write-a-killer-readme/
which is a bit different with a focus on why you would want to use a project before getting into how to install. I have attached the slides here - see also:

• CRAVEX-Docs: Create better, uniform README's across all projects #15 which seems to overlap / duplicate this issue.

How_to_Wr_cHaajL4.pdf

[mjherzog]

The current Why use ScanCode section needs a major rewrite to trim it down. I would remove the bulky paragraph listing package types completely.

[DennisClark]

@mjherzog I inserted the "Why" sentence exactly as written in the aboutcode project near the top of the readme. Renamed the bulky "Why use ScanCode" section to "Benefits of ScanCode" and seriously trimmed the bit about package types.

Current https://github.com/aboutcode-org/scancode-toolkit/blob/new-readme/README.md has the changes.