openwall / openwall/john

Rename documentation files for consistency

Open
#4,357 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation RFC / discussion
Dominant language
C
Stars
13.6k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

jumbo's current documentation files have inconsistent names. Some README* files use a dash (e.g., README-PDF) and others use a dot (e.g., README.BitLocker). I think we should standardize on dashes, keeping uses of dots reserved for filename suffixes indicating file type. Further, some are named very differently like CRAM-MD5.txt, DiskCryptor-HOWTO.md, NETNTLM_README - we should bring these to the same naming scheme (keeping the .md suffix where appropriate).

There's also the question on when to have a filename start with README, if ever. We currently don't do that for most things that are not per-format, and we do it for most things that are per-format. If that's indeed the distinction and if we want to keep it, then maybe some other word in place of README would be more appropriate (any suggestions?)

Now that we have several .md files, should we also start to use .txt suffixes (would be a change from core, but that's OK) or should we drop the few that we already have? Our current use of .txt is inconsistent, and that's probably wrong.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by listing the documentation files named in the issue, including README-PDF, README.BitLocker, CRAM-MD5.txt, DiskCryptor-HOWTO.md, and NETNTLM_README, then compare their naming and suffix patterns. Done means agreeing on the README convention, dash usage, and .md/.txt policy, and applying that scheme consistently across the affected files.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.