1Writers write to be read

Why do we write? Because someone needs to read it. At least your future self should need to read it. The reader is the writer's reason for existing. There is no point in writing something that will not be read. If you can't think of anyone who would read it, don't write it.

Why do we read? So that we do not start from zero. Inter-generation knowledge transfer. Human progress will stop if we have to reinvent everything our ancestors did; we would die only to repeat history. If we live for 80 years, and we need 30 years to catch up with our ancestors' 2000 years of knowledge, then we have 50 years to advance human knowledge.

What should we write? Something that someone needs to read.

  • Why do we read? What do we need to read?
    • Why do we need anything?
      • Either for survival or for curiosity.
      • Human brain has evolved two instincts: survival and curiosity.
        • We become anxious when our survival is threatened.
        • We become happy when our curiosity is satisfied.
        • We become bored when we run out of things that make us curious.
      • Thus the root cause of every human action is either survival or curiosity.
    • Thus we read to survive (avoid death) and decuriousify (to avoid boredom).
  • Rules
    • As long as this site is hosted on GitHub, all contents in this site shall follow the GitHub Terms of Service.
    • Ads are OK as long as they don't hamper the reading experience. They must not slow down the page. They must not cover the content.
    • Pop-ups are not OK.
  • The technology decisions for this wiki and why:
    • Use technology that should still work at least until year 2100.
      • Use only free open-source technologies with proven maintenance track record.
      • Enable rebuilding of the website somewhere else quickly.
    • Use Jekyll-powered GitHub Pages. If GitHub screws us, we buy a new domain, move to AWS, and ask Google to reindex.
    • Use GitHub Flavored Markdown. If Jekyll screws us, we switch to Pandoc.
    • Markdown weaknesses:
      • The original Markdown doesn't have tables.
      • Proliferation of incompatible dialects.
    • Wiki vs blog, page vs post
      • A page is timeless. Its usefulness should not depend on time. Old pages are still useful.
      • A post is time-sensitive. Its usefulness depends on time. Old posts are useless.
      • Posts are good for news, updates, changelogs, diffs.
    • Alternatives?
  • 2017-05-18
    • What to write?
      • Something you want to write.
      • Something a group of people want to read.
  • 2017-05-18
    • Installing Jekyll on Ubuntu 14
      • Ubuntu 14 has Ruby 1.9.1 package and Jekyll 0.11.2.
      • Jekyll 3.4.3 requires Ruby 2.
      • Download Ruby 2.4.1.
      • Run:
      sudo apt-get install libssl-dev bison
cd ruby-2.4.1
configure --prefix=$HOME/.local
make -j4 install

  • Information visualization

  • 2016-04-16T19:32:18Z

    • What should we write?

      • Answers from pragmaticism and capitalism:

        • Write something that our intended audience find useful.
        • Treat our writing as asset.
        • Ask ourselves: what problem are we solving?
      • We can write anything you want to, but we will be a better writer if we understand why people read.

      • People read to solve their problems.

        • Some need to fix a computer; help articles fix their problem.
        • Some need to decide if they will invest in a company; reports fix their problem.

      • We want to write something good. What is a good writing?

        • Let me use pragmaticism and capitalism to define a good writing; you can later define what is good for you according to whatever moral system you subscribe to.

          • Pragmaticism suggests that a good writing is useful in the sense that the writing solves the problem of its intended readers.
          • Capitalism suggests that a good writing is a capital, an asset, a means of production. For example, some novels give rise to films, games, and merchandises; such writings are great assets that will bring wealth to their owners. A writing published on the Internet is also an asset for generating traffic and trust, which can sometimes then translate into money through advertising (or whatever you can convert others' trust to).

2Undigested information

3How much can we read in one sitting? How fast can we read?

What is one sitting? For me it varies between 15 minutes and 30 minutes. One sitting is the amount of time one can continuously sit without hurting any of his eyes, back, and butt.

Assume that I read 500 words per minute with 80% comprehension.

Assume that I read 8 hours (480 minutes) per day.

Thus at best I read 240,000 words per day.

Assume that there are 500 words per page.

Thus at best I read 480 pages per day.

If we fix the eye and move the text instead, we read faster. I can read 1500 words per minute (750 word pairs per minute) with 80% comprehension.

The problem: it doesn't work images and inline math.

Assume that I can listen to 300 wpm screen reader with 80% comprehension.

4Splitting text into sections

We do not split a two-hour speech into chapters. Why do we split a two-hour book into chapters?

Why do we split a book into chapters?

4.1Readers expect text to be split into sections for quick navigation

Readers expect table of contents to quickly determine whether they want to read anything.

4.2Writers split text into sections for simultaneous writing

More sections mean less probability of writer's block.

As a writer, I split my text into sections to

  • recursively outline my ideas
  • work in parallel, edit non-linearly

4.3What should the syntax of section titles be?

There are three possible syntaxes for a section title:

  • a question like "How do we improve productivity?" which is answered by the section body;
  • a statement like "XYZ improves productivity" which is justified by the section body;
  • a noun phrase like "Improving productivity by XYZ" which is elaborated by the section body;
  • an imperative like "Improve your productivity by XYZ" which is decomposed into subcommands by the section body.

The syntax of a section title suggests the purpose of the section:

  • A question title suggests an expository/descriptive section body.
  • A statement title suggests an argumentative/persuasive section body.
  • A noun phrase title suggests an exploratory section body.
  • An imperative title suggests a procedural step-by-step section body.

A section title should not be a question, but if you don't know the answer yet, be ready to replace a question title with a summary of its answer.

The proximate goal of the readers is to obtain knowledge in the most efficient and fun way possible. The proximate goal of the writers is to spread their beliefs, to convince the readers.

"A great title gives away the ending."1 Thus a section's title is a sentence summarizing the section.

A question does not give away the ending.

But what if the section does not have an ending? Research is full of endless speculative explorations.

5Using languages

5.1Parseability is necessary for understandability

"The length of a sentence isn’t what makes it hard to understand—it’s how long you have to wait for a phrase to be completed."2 It gives the example sentence: "While Bob ate an apple was in the basket."

https://en.wikipedia.org/wiki/Garden-path_sentence

5.2Pluralize, when you need a gender-neutral singular third-person pronoun

<2018-11-06> Prescription: Pluralize things and use "they". This is the least hassle.

<2018-11-06> An old prescription I no longer follow:

  • I use "he" as both male and gender-neutral singular third-person pronoun.
  • Ambiguity resolution rules
    • If the context makes sense for both genders, then "he" is gender-neutral.

Some languages don't have this problem. Indonesian has gender-neutral third-person pronoun "dia" and "beliau".

Why the hell does English care about the gender of the third person? We just need one word that means "that person".

English history?

5.3How to write: recursive-modification structures in writing

5.3.1The importance of the first sentence of each paragraph

Write such that the reader can summarize your writing just by reading the first sentence of each paragraph.

5.3.2The table of contents must tell the readers how they will benefit by reading the book.

5.3.3If there is any conclusion, then it should be the first chapter.

5.3.4The abstract explains how the readers will benefit by reading the article.

5.3.5Modification hierarchy

  • Adjective modifies noun.
  • Predicate modifies subject.
  • Support sentence modifies thesis sentence.
  • Support paragraph modifies thesis paragraph.
  • Subsection modifies its parent section.

Example of modification:

  • Car
  • Red car
  • The red car is so expensive.
  • The red car is so expensive. I could buy two houses with that.

Another example:

  • Boy
  • Bad boy
  • He is a bad boy.
  • He is a bad boy. However, he loves his family.

5.3.6Paragraph structure

Every paragraph should have this form: "Thesis. Modifier 1. Modifier 2. … Modifier N."

The first sentence of a paragraph is the paragraph's thesis. The other sentences supports, clarifies, limits, or modifies the thesis.

Bad paragraph: thesis sentence at end of paragraph. "He is a bad boy. She is a bad girl. Together they destroy this family."

Good paragraph: thesis sentence at beginning of paragraph. "The bad boy and the bad girl together destroy this family."

5.4Arguing strongly

5.4.1A strong argument has few objections.

Consider whether the reader can understand.

First, state the thesis.

Then, state the objections. Think of as many objections as you can. Try to refute your own thesis.

Then, state the supports.

Each objection is another argument or an axiom.

Each support is another argument or an axiom.

Write no unnecessary words.

An argument is a chain of reasons.

5.4.2Refuting a definition

We can refute a definition by showing that it leads to undesirable consequences.

5.5Writing

The subject should be short.

The predicate should appear as early as possible.

Example:

  • Bad: "Alice, Bob, Charlie, John, Jack, Jane, and Judy went to the same class."
  • Good: "These people went to the same class: Alice, Bob, Charlie, John, Jack, Jane, Judy."

Example:

  • Bad: "The expensive new red car that once belonged to Alice now belongs to Bob."
  • Good? "The car changed hands from Alice to Bob."
    • I hate idioms and set phrases. They reduce uniformity, consistency, and predictability.

5.6Even technical writing should be narrative

"A group of well-formed sentences does not necessarily form a coherent paragraph. The order in which they are placed can significantly alter the ease with which they can be understood" [1]

The problem with description: it does not tell why. A narration or an argument tells why.

Structuring our writing as narrative may help expose the incoherence.

6Technology for academic writing for screen or web

6.1Writing for screen

  • Design your text so that the reader can read it continuously and can resume arbitrarily.
    • A page should be finishable in one sitting (about 15 minutes perhaps?).
    • Links?
      • Links should be clumped together, not scattered.
        • Links distract. They break the continuity/immersion of the reading.
    • Design the branching points such that readers understand what to expect by following the links.
  • Difference
    • No progress indicator.
      • On paper, your hand tells you how far you are from the end of the book.
      • On screen, you have no idea where you are.
    • No position indicator.
      • On paper, you can mark a page and resume reading later.
      • On screen, you can bookmark a page.
    • Navigation: linear vs tree
      • On paper, navigation is mostly linear: you go to the next page. Occasionally you jump to the table of contents.
        • On screen, navigation is tree.
          • Following links depth-first risks forgetting the original context.
          • Following links breadth-first risks browser tab count explosion.
  • Which feels better: flip pages of paper, or navigate several hyperlinks?

6.2TOC (table of contents), page numbers, word counts, and reading time estimation

I can estimate the time required to read a printed book: I look at its TOC and page numbers.

I can't estimate the time required to read a Web book: There are no page numbers.

To go to a section:

  • Print readers use a page number.
  • Web readers use a link.

To estimate how much time is required to read a section:

  • Print readers use how many pages that section takes.
  • Web readers use number of words in that section.

Thus, in Web book TOC entries, we should substitute page number with word count.

6.3Best font families and sizes for portability and readability

I use Noto font families for my web books.

I need serif fonts and monospaced fonts that mix.

<2019-03-24> I used to use the DejaVu families because they have compatible x-heights and they were pre-installed on Ubuntu 14.04. But Noto is installed by default on Android, and I have moved to Debian 9.

Times New Roman, Arial, and Courier New don't mix: They have painfully different x-heights.

DejaVu and Noto families may only be widely available on libre software platforms. I don't know the situation on Windows and Mac.

<2018-09-19> Web authoring woes: lack of a set of font families with same x-height I need a serif font family, sans-serif font family, a monospaced font family, and a math font family. I want all of them to have the same x-height.

<2019-03-24> There is a partial solution (text and code but without math): families such as Noto and Liberation.

"They found that reading speed is fastest when the text’s x-height is 0.3 degrees of arc." https://www.imarc.com/blog/best-font-size-for-any-device

6.4Don't just collect links. Comment them. Opine. Think.

6.5Academic Web authoring

Jekyll's Liquid markup {% raw %}{% link %}{% endraw %} is dirty and wrong. The semantically correct way is to transform HTML DOM relative links.

The end goal is to generate HTML. So why don't we just write the source in HTML?

  1. Paragraph in table.
  2. Outlining support. Is this important? Jumping around is inefficient. It's more efficient if we write sequentially.

Assumptions:

  • no graphics, no images
  • some mathematics
  • programming language researcher

Write directly in prolog?

document(Id, Meta, ["
\metadata{
}
Hey.

Para \em{strong}.

\a[href=internal:OtherdocId]{whatsit}
"]).
document(Id,

pandoc-scholar https://github.com/pandoc-scholar/pandoc-scholar/blob/master/README.md

"Boilerplating Pandoc for Academic Writing" https://www.soimort.org/notes/161117/

6.6Academic writing technology

Evaluate https://pandoc-scholar.github.io/ "Formatting Open Science: agilely creating multiple document formats for academic manuscripts with Pandoc Scholar"

https://en.wikipedia.org/wiki/Comparison_of_document_markup_languages

Installing cm-super affects pdflatex/xelatex output quality.

  • HTML is low-effort for the reader.
  • LaTeX excels at producing beautiful printable documents.
  • Pandoc (Pandoc custom template + Pandoc Lua filter)

Emacs Lisp programming "Understanding letf and how it replaces flet" http://endlessparentheses.com/understanding-letf-and-how-it-replaces-flet.html

Not everyone agrees. https://www.reddit.com/r/emacs/comments/71wy6n/orgmode_as_a_markup_language_does_make_sense_even/ https://karl-voit.at/2017/09/23/orgmode-as-markup-only/

There are two options for converting Org to HTML: Org Exporter and Pandoc.

Org Exporter is slow.

Pandoc+Lua is better documented?

https://pandoc.org/lua-filters.html#counting-words-in-a-document

6.7Writing technologies?

6.8Combining wiki, blog, and forum?

https://hapgood.us/2016/02/22/can-blogs-and-wiki-be-merged/

  • "Wiki values are often polar opposites of blogging values. Personal voice is meant to be minimized. Voices are meant to be merged. Rather than serial presentation, wiki values treating pages as nodes that stand outside of any particular narrative, and attempt to be timeless rather than timebound reactions." Exactly!
  • Federated wiki tries to merge blog and wiki?
  • "Wikum" combines wiki and forum. It uses recursive summarization
  • https://www.nateliason.com/blog/wiki-strategy

6.9Pandoc woes

pandoc --mathjax -f org -t html philo.org --lua-filter _pandoc/filter.lua

Pandoc: How to avoid generating org-mode custom-id property drawer for internal linking?

Pandoc org output mishandles pipe character in inline math in table cell? Or is the markdown input invalid indeed?

7My opinions about writing

7.1Problem with 2018 writings: books are too long

Books should be structured as an inverted pyramid:

  • Begin with the most important statement.
  • The rest of the book supports that statement.

Books should be much shorter. I think a 100-page popular book has only 1 page of useful information.

7.2My old opinions that I no longer believe

7.2.1Paragraphs should be replaced with bulleted lists.

<2018-11-06> I don't believe this anymore. Paragraphs with first-sentence thesis are more readable.

7.3Encyclopedias should focus on why and not what

Wikipedia is dumb data. Google is dumb data. We need opinion and interpretation to turn data into information.

8Using technology to write

8.1One-time setup

Use Debian 9.

Install Pandoc using apt. (How?)

Download pandoc-scholar from GitHub. (Where? How?)

8.2Usage

Write your content in any markup language that Pandoc can read. I use org mode. Sometimes I also use markdown.

Run Pandoc Scholar:

cd TEMP
make ARTICLE_FILE=... DEFAULT_EXTENSIONS=html

9Writing system

https://www.dedoimedo.com/computers/linux-beginning-of-the-end.html- Can we use pandoc-scholar with org mode?

10Writing (old content)

Writing is a scalable way to spread your ideas.

10.1Reasons for reading fiction

In fiction, you can pretend that you are someone else.

Fiction helps you imagine.

Fiction helps you escape reality.

10.2Deletion

Every word must be important. Use the fewest words to influence the reader.

10.3Respect the reader

The highest honor for a writer is the reader's attention.

10.4Internet

Once it's on the Internet, it's there forever. You can't delete it.

Don't write things that can be used against you.

10.5How to write a book

Write things. Order things. Delete as many as possible. Repeat.

Alternate between focusedly-dip-deep-into-a-section and be-a-generalist-and-read-a-chapter.

A book begins as a bunch of small isolated islands of text containing main ideas and structural drafts.

Write. Make mistakes. Rewrite.

10.6Form

The first sentence of a paragraph makes claim. The rest of the paragraph supports the claim. Thus, the reader can skim by reading the first sentence of every paragraph.

Ordering: If understanding \(B\) depends on understanding \(A\), then \(A\) must come before \(B\) in the text. Don't make the reader jump around.

Define uncommon term before using it.

Grouping: Related text should be near.

Non-redundancy: Never waste what the reader has read.

Clarity: If the reader reads the book linearly, then he/she should understand a sentence just by reading it once. The reader should parse the sentence in one pass. Avoid ambiguous syntax.

Avoid garden path sentences. Readers must parse a sentence before they understand it. Understanding is hard. Parsing adds unnecessary difficulty.

10.7Why a book, not a website?

A book has pages. Pages help readers estimate the amount of material. Pages help readers estimate the amount of time they have to invest. Pages are significant visual cue. Online text seems endless. Links distract.

After reading , we conclude: The subjects of the sentences in a paragraph should match the paragraph's topic. IF passivating a sentence would match its subject to the topic of the containing paragraph, then passivate it. Don't mindlessly activate all sentences.

There is a summary.3

LaTeX

11What is writing?

Writing can be separated into insertion and reorganization:

  • Insert new text, sentence, section.
  • Move/shuffle/reorganize text, sentence, section.
  • Delete text, sentence, section.
  • Revise/update/change text, sentence, section.
  • Change section title.

Reverse writing: Imagine that your writing were finished and you were reading that finished writing. What would you read?

12Should I write a book or an article?

An article.

Article is shorter and more focused.

It is easier to write an article than a book.

Also, Google crawler limits page size.

13English orthography problems

We know a language is fucked up if its native speakers have difficulty spelling:

  • lots of fucked-up examples in English StackExchange4
  • English speakers on Reddit share their difficulties5
  • "Now all of these people are native speakers of English and are smart people, but occasionally they mispronounce a word. And occasionally people on radio and television will mispronounce a word."6

Some problems with English:

  • determine, undermine
  • surface, preface, deface
  • indict, indite
  • debt, doubt, subtle
  • history, hour, our
  • desert, desert, desert, dessert
  • way, weigh, whey
  • stationary, stationery
  • awe, owe, awry
  • pint, hint

Harriet Staff quotes Stephen Fry7:

[…] The French language, like Paris, has attempted, through its Academy, to retain its purity, to fight the advancing tides of franglais and international prefabrication. English, by comparison, is a shameless whore.

14Typography notes

Bullet lists and one-line indented paragraphs don't mix. They look hideous. But space-separated paragraphs waste space.

15Bibliography

[1] De Silva, N.H. and Henderson, P. 2007. Narrative-based writing for coherent technical documents. Proceedings of the 25th annual acm international conference on design of communication (2007), 208–215. url: <https://eprints.soton.ac.uk/264969/1/sigdoc46-desilva.pdf>.

  1. https://writing.stackexchange.com/questions/14516/can-section-headings-in-a-paper-be-questions↩

  2. https://www.businessinsider.com/why-this-sentence-is-hard-to-understand-2015-3/↩

  3. https://www.crowl.org/Lawrence/writing/GopenSwan90.html↩

  4. https://ell.stackexchange.com/questions/37048/how-can-native-english-speakers-read-an-unknown-word-correctly/37049↩

  5. https://www.reddit.com/r/AskReddit/comments/eha38/which_words_did_you_mispronounce_for_years/↩

  6. https://loxleyspeechstudio.com/native-english-mispronounce/↩

  7. https://www.poetryfoundation.org/harriet/2011/07/english-is-a-shameless-whore↩