Pond’ring Aloud: Writing Articles, Blog Posts (Part 3)

2025-01-04

Paul Tarvydas

Jan 04, 2025

[This is part 3]

Part 1

Part 2

Goal

To transfer technical information in the least painful way for the reader.

To make creating such information easier for the writer.

To figure out which tools I should be using to write with. I believe in brainstorming. I believe that it is OK to be wrong and to backtrack and to reverse your decisions, given new information based on new discoveries about your target problem space. I believe in “showing your intermediate work” (for partial marks). This article is a stream-of-consciouness pile of text that lays out my options - conclusions to come later. Hopefully, my options will become more clear once I write about them...

In this part, I list a bunch of observations, but I haven’t made any final conclusions / decisions yet.

Concepts

More Diagrams, Less Text

[See Part 1]

Layering

The written word, also, has the effect of flattening broad concepts. Academic papers are a good example.

When one approaches a new concept, one would like to start with a broad overview.

When one becomes expert in a concept, one tries to compress the concept down to its smallest form - to express it as succinctly as possible. Hence, the use of Greek letters in mathematics. Each letter used in an equation carries a lot of baggage - a huge pile of concepts. Unless you are another expert, the conciseness of an equation tends to be a barrier to entry - it’s hard to understand what an equation means because the meaning has been compressed and flattened and caries too much hidden detail.

At the opposite end are trends like YouTube, Facebook, Instagram, etc. They get an idea across quickly, but, don’t go very deeply. It’s hard to say anything meaningful in only 140 characters of prose, i.e. non-equation text.

The choices are:

Decide that your audience is composed of experts and write equations
Decide that your audience is composed of non-experts and write fluff
Use layers to address audiences at both ends of the spectrum and work towards middle ground by successively adding layers of detail. Readers can quit at any level. Readers can begin at any end.

Gutenberg Printing Press

Benefits

- Direct relationship to spoken language

- Opened up the transfer of knowledge to a much larger population.

Damage Caused

The printing press linearized thought by further linearizing the written word and disallowing non-type-settable annotations (like the vinculum). We can think and perceive in many dimensions at once (sight, sound, touch, etc.), but the printed word forces us to use only one dimension (sight, reading in only one direction, e.g. left-to-right, top-to-bottom (in Western language)).

The printing press damaged mathematical notation[1].

Tools

Markdown and Github Pages

makes including diagrams more difficult, hence, one is less likely to use diagrams
Markdown was designed with the idea that documents should be text
Markdown is essentially a DSL designed to simplify HTML for writing text - a good idea, except that it emphasizes text over images ; images are an after-thought in markdown

Substack

https://substack.com/

You must use the substack editor
The editor does not understand markdown files
Allows you to copy/paste from Apple Pages directly into the editor, and gets the bulk of the text right
- Converts “Headings” into bold text. You need to revisit each heading and select an appropriate markdown-like heading.
- Completely misses all images. You have to copy / paste every image one-by-one from Apple Pages into the Substack editor. When done, this shows the image inline without extra clicking by the person reading the post.
- Completely misses all footnotes. Each footnote needs to be copy / pasted into a Substack footnote. This behaviour causes me to avoid using footnotes in Apple Pages entirely, but, sometimes I can’t resist.
You have to choose a “Social Preview” image through “Settings” manually for each post. If you include an image or a video in the post, Substack gets the “Social Preview” setting right, but, for text-only articles, you have to remember to set this manually.
Substack formats your post for use on a smartphone and allows you to preview it.
Substack allows you to make your articles free, while making some articles paid-for.
Substack automatically sets up a mailing list of subscribers (free and paid) and handles some SEO issues. I don’t want to deal with any of that stuff, so I’m happy to punt the work to Substack.

YouTube

https://www.youtube.com/
Allows you to upload videos.
Manages videos using “playlists”.
YouTube contains a lot of non-technical videos. This clutters the environment. I don’t know how to “get discovered”. I don’t know how to let potential subscribers find my work.
You have to get into the habit of checking your account on a daily basis to see if there are any comments, etc.
I use Descript to help me edit my videos (see below).
I tried OBS, iMovie, etc. and found timeline-based editing to be painful. For my purposes, Descript is better.

Apple Pages

more than just a word processor, it’s a page layout tool
Closed source, proprietary format, not compatible with anything else
Well-integrated into the Apple ecosystem, works on multiple devices (iPhone, iPad, just about anything that uses MacOS, etc)
Very convenient, except that for the proprietary format
I use EndNote to insert citations.
- The Apple plug-in for EndNote has many fewer features than the Word version.
Other citation management tools like Zotero are not automatically supported / integrated.
Can produce PDF and ePub files. I need to explore where best to upload these (Github pages, vs. Gumroad, vs. ???)

Apple Keynote

amazing features
Instant visual feedback when editing (my favourite editor for writing concise text), due to automatic font-resizing
Not compatible with Apple Pages. No export to Apple Pages. At best, you can use Copy/Paste to extract text to the clipboard.
Goofy large HTML export - exports each page as an image, HTML is just a javascript script that displays the images.
Provides powerful animation features
Doesn’t support EndNote for citations.
Each slide can contain a “transition” effect.
Each element on each slide can be scripted by a “transition” effect, too. An element “script” is broken into 3 canned parts:

Build in - how the element arrives on the slide
Action - various complicated canned actions for displaying the element
Build out - how the element is removed from the slide

“Scripts” can be sequenced using canned choices, e.g. immediately after the slide appears, on click, following the previous sequencing item.
- Apparently, this is all that non-programmers need. They don’t need general purpose program control flow.

Descript

https://www.descript.com/

Smart use of AI for editing video.
Much better than timeline-editing for video. [Timeline editing is similar to that found in DAWs]
Records video, then transcribes audio. Lets you edit the video by editing the transcription with a built-in word processor. Much, much better than timeline editing.

Drawio.io

Diagram editor[2]
Lots of libraries of shapes that I mostly don’t use.
I use draw.io for 0D[3].
Saves drawings in an XML format called graphML[4]. This format is textual and can be inhaled by software to automatically generate code, using an XML parser. Some of the graphical-only information is voluminous and can be culled out prior to processing, as in https://programmingsimplicity.substack.com/p/towards-diagram-compilation
I use the “Sketch” checkbox to make the diagram look less technical
I use 2pt wide, solid line arrows for important connections, connections that I want to emphasize at the Architectural level
I use 1pt, dotted line arrows for less important, architecturally, connections, like error flows
Boxes at the top level are understood to be software parts, regardless of colour, size
boxes that intersect top-level boxes are understood to be ports
- White boxes are input ports
- Teal boxes are output ports
Rhombuses are understood to be gates (top-level ports), white rhombuses are input gates, teal rhombuses are output gates
Most everything else is ignored as comments

Apple MacOS vs. Linux vs. Windows

I’ve used all 3 operating systems.
MacOS is best for creative endeavours like writing.
- MacOS is OK for code development
  - Supports Emacs, but M-X shell does not have access to the full path when Brew is used to install tools.
- Well-integrated with other devices like iPhone, iPad - this is better than Dropbox
- iCloud is like Dropbox, but better integrated across the full line of Apple devices
- iCloud does not play well with github
  - I use git on iCloud synced disk, but, am careful never to push to github
  - For projects I want to push to github, I use a non-iCloud drive and put the projects there
- MacOS uses Python2.7, as a developer, I need to side-step around the built-in Python and use a separate copy of Python for my work (I happen to use Python3, and I need to ensure that I don’t upset any MacOS system app with my version of Python3)
- MacOS cannot do “focus-follows-mouse”. In fact, MacOS is schizophrenic. It will scroll whichever window the mouse is in, but, you have to remember to click for focus before entering any text via the keyboard. This behaviour is a continuous source of confusion and frustration for me, but, it seems not to be bad enough to cause me to switch back to Linux.
Linux is ostensibly free, but, you end up paying for this with your own time, setting options, looking for tools
- Lacks many writing tools available on MacOS, like a good WYSIWYG word processor
- Not as well integrated as MacOS with various devices, like iPhone and iPad
- I escaped from Linux and don’t expect to return to it
- The constant need for attending to details derails one’s ability to develop software and to write articles - Linux is only good for waterfall development because of the continuous need to attend to interruptions
- A bag of options, not conducive to actually doing Software Design work.
I escaped from Windows many years ago and don’t expect to return to it
- My mother’s laptop runs Windows and I don’t see any advantage in Windows over MacOS for creative apps
- Windows appears to be geared for business, rather than independent people

Scrivener

a bag of options, hard to learn
primarily designed for Mac, Windows is an afterthought, I’m not aware that a Linux version exists

Obsidian

markdown editor
Has it’s own file manager
Uses wikilinks
A wall of disparate options
Huge community of users, adding more plugins, creating a wall of plugins
Doesn’t produce files that are compatible with github pages out-of-the-box

Emacs

a wall of options, hard to learn
Capable of doing just about anything, emacs is the first place that new ideas appear in

Gumroad

a way to monetize content (PDF, ePub)
I haven’t explored it enough to figure out what the gotchas are

Leanpub

a way to produce written-text books using markdown
provides it’s own dialect of markdown - Markua - that is a superset of markdown that addresses all the niggly details of producing a book
Meant for incremental publishing of books - encourages releasing books before they are finished and encourages incremental progress on such books until they are “finished”
Lots of details and options, I grew tired of dealing with all the details, albeit necessary

Wick Editor

modern, open-source free version of “Flash”
Editor is based on timelines
Apparently “abandoned”, github hasn’t been updated for a while
I think that the mark of bug-less software is that it hasn’t been updated for a while, others think that constant updating is a vital sign of life

Excalidraw

makes drawing sketches easy
File-saving is a disaster - it saves files by downloading versions to your Downloads folder, but, you need to remember to change the target filename or else it will overwrite previous work

LaTeX

Favoured for ACM conference papers
Painful to use
I found that the ACM template did not integrate well with WYSIWG LaTeX editors. This resulted in a painful, sluggish edit-compile-view cycle.
I will avoid LaTeX in the future, since Apple Pages does everything I need (and more).

Bibliography

[1] James Tanton. The Story of the Vinculum from

[2] Draw.io from https://app.diagrams.net

[3] 0D from https://github.com/guitarvydas/0D

[4] GraphML from http://graphml.graphdrawing.org

Paul’s Substack

Discussion about this post