Skip to content

Writing

Writing is difficult, at least for me. Even more if you aren't using your native tongue. I'm focusing my efforts in improving my grammar and orthography and writing style.

Tests⚑

Using automatic tools that highlight the violations of the previous principles may help you to internalize all the measures, even more with the new ones.

Configure your editor to:

  • Run a spell checker that you can check as you write.
  • Alert you on new orthography rules you want to adopt.
  • Use linters to raise your awareness on the rest of issues.
    • alex to find gender favoring, polarizing, race related, religion inconsiderate, or other unequal phrasing in text.
    • markdownlint: style checker and lint tool for Markdown/CommonMark files.
    • proselint: Is another linter for prose.
    • write-good is a naive linter for English prose.
  • Use formatters to make your writing experience more pleasant.
    • mdformat: I haven't tested it yet, but looks promising.

There are some checks that I wasn't able to adopt:

  • Try to use less than 30 words per sentence.
  • Check that every sentence is ended with a dot.
  • Be consistent across document structures, use References instead of Links, or Installation instead of Install.
  • gwern markdown-lint.sh script file.
  • Avoid the use of here, use descriptive link text.
  • Rotten links: use linkchecker (I think there was a mkdocs plugin to do this). Also read how to archive urls.

  • check for use of the word "significant"/"significance" and insert "[statistically]" as appropriate (to disambiguate between effect sizes and statistical significance; this common confusion is one reason for "statistical-significance considered harmful")

  • To make your writing concise: write your first draft, get its word count, then multiply that number by 0.9 (90%). Cut your writing down to that new word count.

Vim enhancements⚑

  • vim-pencil looks promising but it's still not ready
  • mdnav opens links to urls or files when pressing enter in normal mode over a markdown link, similar to gx but more powerful. I specially like the ability of following [self referencing link][] links, that allows storing the links at the bottom.

Writing workflow⚑

  • Start with a template.
  • Use synoptical reading to gather ideas in an unconnected thoughts section.
  • Once you've got several refactor them in sections with markdown headers.
  • Ideally you'll want to wrap your whole blog post into a story or timeline.
  • Add an abstract so the reader may decide if she wants to read it.

Publication⚑

  • Think how to publicize:
  • Hacker News
  • Reddit
  • LessWrong (and further sites as appropriate)

References⚑

Awesome:

Good:

Doing⚑

Todo⚑

Vim plugins⚑

Books⚑