Jak snadno vylepšit kvalitu dokumentace a psaného projevu obecně

  •   2 minutes read
Když už píšeme dokumentaci — README.md nebo cokoli jiného, hodí se mít nástroj pro kontrolu textu — nejlépe překlepů, pravopisu a gramatiky.

Textlint — angličtina, japonština

Používáme-li nějaké vývojové prostředí, určitě se hodí Textlint, který umí hlídat i opravovat:

  • validní (fungující) odkazy,
  • konzistentní terminologii, jako JavaScript vs. Java​script nebo npm vs. N​PM,
  • vylepšuje jazykovou barvitost blokováním slovíček jako ju​st, easi​ly a si​mply,
  • křičí při výskytu TODO atp.

Hřiště pro zkoušení možností
Doplněk do VS code

Instalace a použití

Instalace do projektu

npm i -D textlint &&
npm i -D textlint-rule-common-misspellings &&
npm i -D textlint-rule-no-dead-link &&
npm i -D textlint-rule-terminology &&
npm i -D textlint-rule-write-good

Konfigurační soubor s pravidly .textlintrc.yml umístěný v rootu projektu

rules:
  terminology: true
  common-misspellings: true
  write-good:
    adverb: false
    passive: false
    tooWordy: false
    weasel: false
  no-dead-link: true

Nastavení zkratek pro spuštění v package.json

"scripts": {
  "text:lint": "textlint *.md",
  "text:fix": "textlint --fix *.md"
}

Spuštění kontroly v CLI (příkazové řádce)

npm run text:lint

Spuštění oprav

npm run text:fix

Proselint — angličtina

Jednoduše linter na prózu , tedy něco jako další kontrola gramatiky. Zaměřuje se na výskyty redundance, žargonu, nelogičností, klišé, sexismu, pravopisu, nekonzistence, oxymoronů atd. Bohužel pro svůj běh potřebuje Python resp. pip a pak běží na CLI.

Grammarly® — angličtina

Metr na gramatiku, opravuje tvary, překlepy i členy. Vše formou nápovědy s vysvětlením — člověk se i něco naučí. I v neplacené verzi velmi použitelný. Momentálně nejlepší řešení na trhu. Funguje jako samostatná webová aplikace, rozšíření do Chrome , Windows nebo Microsoft® Office.

Další v pořadí

  • Ginger (angličtina) — přímá konkurence Grammarly, je o facku za nimi.
  • Microsoft® Office (čeština a další) — na trhu stále nejlepší opravy pravopisných chyb, ale s gramatikou mu to jde hůře.
  • Google Dokumenty (čeština a další) — zadarmo, asi tak o polovinu horší než MS Office.
  • Google Chrome (čeština a další) — v blocích pro editaci textu označuje chyby (červeně podtržené) a gramatické nedostatky (šedé podtržení). Navrhované možnosti jsou celkem relevantní a hlavně se nemusí nic instalovat ani konfigurovat.
  • Korektor (čeština) — od české společnosti Lingea, slouží k doplnění diakritiky a kontroly pravopisu.
  • SpellCheckPlus (angličtina) — webová stránka, celkem to ujde.
  • After the Deadline — webové stránka i kknihovky pro vývojáře, výsledky nic moc.
  • Lingea Grammaticon (čeština) — téměř už rarita, ale levnější než celá MS Word :-)

Závěr

Kvalitních, automatických a levných nástrojů pro lintování (analýza, kontrola, návrhy a opravy) textů není mnoho. Stačí si vybrat pro danou potřebu z nástrojů výše nebo skusit najít ještě něco jiného.