Large docs

Question: Would splitting the document make it easier to find and maintain, or does it mainly record past work?

• Runs: when selected: --rule large-docs, --rule documentation or --rule all · Fails the check by default: no
• Right on projects JevGate was never tuned on: considers 1 of 1 (how it is measured)
• Right on the projects it was tuned on: considers 1 of 5
• Looks at: project Markdown of 300 or more lines: root files, README and CONTRIBUTING anywhere, docs/ and doc/ (read even when ignored)
• Evidence unit: one document’s headings in order, without its text
• Acceptable: One long guide, reference or concept, and living procedures
• Names: documentation/large-docs, large-docs, large_docs · Version: 4

When a finding is right

A finding says a long document would be easier to find and maintain split by subject, or that it mainly records past work. It is right for a runbook that holds unrelated subjects, or a finished plan kept among the living documents. It is wrong for one long guide or reference written for one reader, such as a contributing guide. More than a third of the findings labeled wrong were plans covering one release, which read as several subjects from their headings.

A document is judged from its headings alone, and a split finding is asked what kind of document it is: a kind that serves one subject clears it.

Findings it got wrong

Labeled wrong by reading the code, on open-source projects the rules were tuned on.

Django Debug Toolbar: contributing.rst

• Where: docs/contributing.rst:1 in django-commons/django-debug-toolbar at dfc69d9.
• Finding (consider): docs/contributing.rst holds several unrelated subjects.
• Why it was wrong: It is a 301-line contributing guide for one reader, the contributor: bug reports, code, architecture, tests, style, patches, translations, releases and building the docs are the usual sections of such a guide. Splitting it would scatter one guide.
• Since: not addressed; reported the same way from 0.19.0 through 0.25.0.