[DOCS] line length inconsistency · Issue #5522 · npm/cli · GitHub
Skip to content

[DOCS] line length inconsistency #5522

Open

Description

@mrienstra

Is there an existing issue for this?

  • I have searched the existing issues

This is a CLI Docs Problem, not another kind of Docs Problem.

  • This is a CLI Docs Problem.

Description of Problem

Very minor! Two things I noticed while working on #5521, that other careful editors may be confused by (not know what the norms are):

1. Lines longer than 80 characters (outside of codeblocks).

I searched for:
^.{81}
(including *.md files, and excluding CHANGELOG.md,CHANGELOG-*.md files)

Seems like there are lots of exceptions*, should those be fixed, and should that norm (of wrapping in docs .md files) be documented somewhere? Or maybe it makes more sense to get rid of line limits in doc .md files, if it's not going to be enforced?

*: 131, if you also exclude CONTRIBUTING.md,DEPENDENCIES.md,README.md,SECURITY.md, but this count also includes code blocks.

2. Two spaces after periods.

I searched for:
\. {2}[^. ]: 471 results
and:
\. {1}[^. ]: 840 results
(including *.md files, and excluding CHANGELOG.md,CHANGELOG-*.md files)

So incredibly minor, probably not worth fixing, but thought I'd check -- when editing, what is preferred? One space is "winning", so I assumed that's the norm, and changed it in the paragraphs I rewrapped.

Potential Solution

1. Lines longer than 80 characters (outside of codeblocks).

Fix, and document norms in a discoverable place. CONTRIBUTING.md could have a section, or docs/README.md could be used for this purpose, or docs/CONTRIBUTING.md could be created and used.

2. Two spaces after periods.

These seems borderline too minor to fix or document, but I'm still tempted to fix some, just to tip the scales even more decisively, so it's more clear what the norm is. Assuming that's one space, if it's two, then there would be a bit more work to do to make that clear.

Activity

  1. changed the title [-][DOCS] <title>[/-] [+][DOCS] line length inconsistency[/+] on Sep 29, 2022
  2. self-assigned this
    on Oct 27, 2022
  3. added
    Enhancementnew feature or improvement
    and removed
    Needs Triageneeds review for next steps
    on Oct 27, 2022
  4. lukekarrys commented on Oct 27, 2022

    @lukekarrys
    Contributor

    I also want to know the answer to these questions 😁

    It would be great to get consensus from the team and possibly re-evaluate the reasoning here, especially for the 80 char hard wrapping of markdown.

    Personally, I find myself using the GitHub UI more and more, especially the mobile app. It currently is very difficult to read raw markdown there due to how line breaks are rendered.

  5. removed their assignment
    on May 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Documentationdocumentation related issueEnhancementnew feature or improvement

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions