Exporting with citations

Many thanks for your super helpful reply! Sorry I’ve been slow to get back, life has very much intervened :frowning:

Unfortunately, I’m still struggling.

I replaced the pandoc plugin with your suggested Enhanced Export Plugin, which does seem easier to configure, and successfully produces Word docs. So that is a win.

I still can’t work out how to produce Word docs with formatted citations though.

Within Obsidian the Pandoc Reference List plugin renders the following:

  • [@Jones_2024] renders as (Jones, 2024).
  • @Jones_2024 renders as Jones (2024)
  • @[Jones_2024] renders as @[Jones_2024] - not formatted

When I export these to a doc they appear as non-formatted plain text

Clearly, the export plugin needs further configuration to do formatting. Its documentation does link to a walkthrough, but it is behind a paywall at medium.com, so not accessible.

Fortunately, the pandoc manual page you list does suggest what some of this might be. Unfortunately, it’s written at a technical level of detail I’m not equipped to follow. I’m a beginner to all of this; command line arguments and YAML are foreign languages to me. I’m sure they are learnable, but so is French. Nevertheless, I’m sure we can work this out.

The documentation page it links is probably helpful, but assumes a level of technical knowledge I do not have.

It says to trigger citations with:

pandoc --citeproc myinput.txt

I’m trying to use the menu option (“Enhancing Export: Export to…”), so when you invoke that command it already knows the input and output files, and you don’t need to type the “pandoc” command. There is a place in the configuration menu for that plugin for “Extra arguments” and I put --citeproc in there, but that doesn’t seem to do anything on its own.

This is probably because it doesn’t know what format to use. The instructions on the pandoc manual page do further specify:

To use this feature, you will need to have

  • a document containing citations (see Citation syntax);
  • a source of bibliographic data: either an external bibliography file or a list of references in the document’s YAML metadata;
  • optionally, a CSL citation style.

My document has citations in it so I have the first bullet point. I don’t know how I would link an external document, or what external document I should link if so. I understand YAML to be some form of code that you insert at the start of a file, but I don’t know how to write it, and I don’t want to start every single document by pasting in lines of code - that seems repetitively labour-intensive.

The page further says

You can specify an external bibliography using the bibliography metadata field in a YAML metadata section or the --bibliography command line argument. If you want to use multiple bibliography files, you can supply multiple --bibliography arguments or set bibliography metadata field to YAML array.

I tried adding --bibliography to the Extra Arguments filed, but that doesn’t seem to do anything. So again, there clearly has to be some kind of link to some sort of file that is somewhere on my computer, but it isn’t immediately clear what that would be.

I do apologize if I expressed frustration above. I suppose I was expecting this to be a function that worked more out-of-the-box, and not something that requires this much technical knowledge to wire together. Googling how to do it had been throwing out tutorials that made it look easy, but were apparently outdated (i.e., directing to the pandoc plugin).

If the citekeys remain as citekeys, then you haven’t implemented my suggestions. So, although you switched plugin, you’re still facing the same issue of a missing bibliography. --citeproc can’t do anything without a bibliography.

These plugins are both just scaffolding for Pandoc. What you need to do doesn’t change (much) because of the scaffolding, because it’s still Pandoc behind the scenes. Of course, it might vary how you specify the arguments.

The “Extra arguments” field is just a convenient field the that both Pandoc plugins provide where you can add additional arguments into the main command used to run Pandoc. You could in fact also place these arguments there in the field above Extra arguments.

Exactly, it doesn’t do anything on its own. How could it know what @Jones_2024 is referring to without the associated metadata?

This is indeed the sticking point. The type of file you need is explained here: Pandoc User Guide → Citations → Specifying Bibliographic Data.

Basically, you specify it like so:
--bibliography="C:/path/to/your/bibliography.bib"

Where bibliography.bib can a bibtex (.bib), biblatex (.bib), CSL JSON (.json), CSL YAML (.yml), or a RIS (.ris) bibliography file exported from a reference manager like Zotero.

After this, you’ll have requirements 1. (citeproc) and 2. (bibliography) down. Then you just need to specify the citation style using --csl. Here, you provide a file path or URL to a .csl file, the same way you do for --bibliography.


Live citations in Word

Since you seem focused on Word exports, you should be aware that using --citeproc might not be the best option in this case, because it will give you static citations that you can’t dynamically edit in Word (change citation style, update bibliography list). For other exports like PDF, stick with --citeproc and its associated arguments.

But if you want editable citations in Word, like the ones you get when using the Zotero addon for Word, there is another option.

This option is to use a filter made be retorquere (the Better Bibtex creator). Find the relevant guide here:

  1. Download the zotero.lua filter from the link above.
  2. Find your Pandoc user data folder using the pandoc --version command in your OS’s terminal / command prompt.
    • In this Pandoc folder, create a “filters” subfolder, and put the downloaded zotero.lua file into this folder.
    • If no such user data folder exists at path you found in the terminal, create it and then also the aformentioned “filters” folder.
  3. Put the following argument in the extra arguments of your command template for Word (docx) exports in Enhancing Export’s settings:
    --lua-filter zotero.lua
    
    • Double-check that you selected the right command template: Edit command template → Choose template → Word (.docx) template, before making any changes!
    • Make sure to remove the --citeproc, --bibliography, --csl arguments, if you had added these. The zotero.lua filter will handle all this instead.
  4. If necessary, specify additional arguments for zotero.lua.
    • For example, if you are citing items in a group library, you should specify that with the library property (see below).
    • This can be done in the note’s properties, like so:
---
# all the regular stuff you have here
zotero:
  library: <group name> # omitted to use your personal library
  scannable-cite: false # only relevant when you're compiling to scannable-cite .odt
  client: <zotero or jurism> # defaults to zotero
  author-in-text: false # when true, enabled fake author-name-only cites by replacing it with the text of the last names of the authors
  csl-style: apa # pre-fill the style
  sorted: true # sort clustered citations by author.
---

or using additional arguments placed in Extra arguments field like so:
--metadata=zotero_csl-style:apa

  1. Export using the “Enhancing Export: Export to Word” command in the command palette.
  2. In Word, open the Zotero tab and then open Document Preferences → then press OK. Now your citations are live Word citations, and you can update the citations and bibliography! :tada:
5 Likes

Just to clarify the above, adding something like --bibliography="${vaultDir}/Metadata/Zotero/library.bib" --citeproc --csl="${vaultDir}/Metadata/ieee.csl" to the “Extra arguments” field of the Enhancing Export plugin settings and then going through the export steps for that plugin on the same template type should result in formatted inline citations?

I’ve tried this a few times now, changing around absolute and relative paths. All build successfully but they do not produce the expected rendering. I get the same @something strings in the final document and no references list.

Enhancing Export: v1.10.3
Pandoc: v3.1.11.1
Obsidian App: v1.5.3

Edit: I did also try reloading Obsidian after adding the plugin. This cleared out any changes I made in the “Extra arguments” field. I have also tried putting the above arguments directly into the “Arguments” field with no change in behavior.

Yes, that should work.

Sorry for not getting back to you sooner. Is it still not working for you? Which format are you exporting to in this scenario, where it’s not working? Do you get any errors in the console? Can you share a screenshot or copy paste of your arguments?

That’s a real bummer, and perhaps why it’s not working? I experienced a similar issue before, but that was fixed. Perhaps the same thing is happening again? You should report it on the Github repo :slight_smile:

Sorry, I’m afraid I’m still not getting it to work :frowning:

I have tried the following:

Changing extra arguments to read (without line breaks):

--citeproc 
--csl="https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl" 
--bibliography="C:\Users\name\OneDrive - institution\path\My Zotero Library.bib" 

The resulting Word file is still not formatted (it still reads [@name_year]).

You are correct that I’m fixated on Word, as it is the lingua franca for much of academia (for worse or worse). I therefore tried following your instructions for the lua filter.

My powershell says the version is 3.1.11.1, and the user data directory is:
C:\Users\name\AppData\Roaming\pandoc

File explorer did not find a ‘pandoc’ directory within the ‘Roaming’ folder, so I created one with that name. Windows did not complain about this duplicating any existing directory names, so I assume (incorrectly?) that I am not missing a folder that is simply hidden.

I then created a \filters folder, and within this a file called pandoc.lua into which I pasted the text from the download that you so helpfully linked.

I changed the Extra Argumnets to read --lua-filter zotero.lua, deleting all the citeproc elements listed above.

When I export the document, there is still no formatting. I added the following to the start of the document:

---
zotero: 
	csl-style: "apa"
	sorted: "true"
---

This also seems to have no effect.

I’m afraid I’m feeling a little defeated. Am I missing something obvious? Am I being a numpty?

For reference, pandoc itself is working: citations are rendered correctly within Obsidian.

Do you get any errors in the console? I would expect there to be some error(s), but you haven’t made it clear whether you’ve checked the console yet. So do check the console (instructions here), and try using double backslashes in the path \\, or forward slashes.

There was a mistake made in the process, namely naming the filter pandoc.lua instead of zotero.lua:

This won’t work, as you are calling a filter named zotero.lua, which doesn’t exist:

So the file names of the filter don’t match as is. You should rename pandoc.lua to zotero.lua. Or alternatively, use the argument --lua-filter pandoc.lua, so long as the filenames match! (I would go with option number one, though).


You were right to create the user data directory yourself. For some reason, it’s not always present by default.

There was something you missed, so cheer up, there is hope yet :wink:

It’s not Pandoc doing that, though. Despite the name, Pandoc Reference List only uses Pandoc to convert bibliography files from .bib to .json, as required. I believe the name refers to the fact that it picks up on Pandoc citations and creates a reference list for those. I believe that the citation parsing is a custom implementation made by mgmeyers, and the citation rendering is citeproc.js, not Pandoc’s citeproc.

Ok, well that’s encouraging.

I switched the name of the file to pandoc.lua and updated that to be the same in Obsidian, but that still is not working.

Thanks for pointing me towards the console.

When I first load the document there is a red error which reads:

TypeError: Cannot read properties of undefined (reading 'editor')
    at t.get (app.js:1:2091356)
    at getEditorFromState (plugin:obsidian-outliner:88:13)
    at VerticalLinesPluginValue.waitForEditor (plugin:obsidian-outliner:2552:28)
    at new VerticalLinesPluginValue (plugin:obsidian-outliner:2602:14)
    at e.eval [as create] (plugin:obsidian-outliner:2795:82)
    at e.update (app.js:1:367539)
    at e.setState (app.js:1:468006)
    at t.clear (app.js:1:1378062)
    at t.clear (app.js:1:2086260)
    at t [as constructor] (app.js:1:1374961)

I don’t know really what that means.

When I try exporting to docx it throws a yellow warning:

plugin:obsidian-tasks-plugin:149 [2024-02-29-14:09:09.738]
[warn][tasks.Cache]
indexFile: WARNING: indexing non-markdown file: folder_path/file_name.docx 

Again, not quite sure how to interpret this.

I guess I really am a numpty!

If you could be more specific than “still is not working” that would be helpful. So you changed the filename (why, wasn’t it already pandoc.lua? Previously, you said: “I then created a \filters folder, and within this a file called pandoc.lua”) and you changed the filter to be --lua-filter pandoc.lua (correct?) - and then what happened? Did Enhancing export give a pop-up notification like this:

image

Or did it pop up an error message? Or did none of those things happen?

As for the console error and warning you mention, the first one doesn’t seem related, and the second one doesn’t seem to interfere. But it’s worth trying to disable both of those before running an export, just to see if there could be any interference.

By the way, when you say that the citekeys are still showing, does it look like this? (including the “Do Zotero Refresh”):

If so, then everything is actually working now, because this is the expected result. The next step is to open the Zotero tab in Word, then open the document preferences and press okay. This converts citations into proper Zotero citations that you can edit:

image

Lastly, if the above is not the case, did you try specifying the bibliography and CSL file like this as I suggested:

I apologise for my lack of specificity.

Currently, I’m trying the lua filter version so there are no backslashes to make double. My configuration of the Enhanced Export plugin looks like this:

(there is no space in pandoc.lua, no matter what that appears to be)

My file in pandoc/filters is this:

image

Unless you mean its link to the Pandoc path, which looks like this:

image

What I mean by “not working” is that I start with text in Obsidian looking like this:

Note: the same citation is there in multiple formats for testing purposes. The raw markup text for the three is, in order:

@[cathelat_2019]
[@cathelat_2019]
@cathelat_2019

A Word docx is indeed produced, but it renders like this:

Unless I am mistaken, these citations appear to be in raw unformatted markup.

Does that help at all?

You’re right! Sorry.

No, I was just confused by the fact that you first said:

And then:

Which would indicate that the name wasn’t already pandoc.lua, so it’s a contradiction.

Sidenote, the following is an invalid citation:


It appears so.

You still didn’t answer this:

Nor did you tell me if you tested this:

So it’s a bit tedious to only get half the answers each time.

Lengthy back-and-forth threads are an inherently confusing format.
The process for creating the file was:

  1. Open ‘c:\Users\name\AppData\Roaming’, and create new folders such that the path becomes ‘c:\Users\name\AppData\Roaming\pandoc\filters’
  2. Create a new text file, which appears with the default name: ‘New Text Document.txt’
  3. open this text file and paste in lua code (as retrieved from the web)
  4. rename text file as ‘zotero.lua’
  5. get told in this forum that it should have been named ‘pandoc.lua’
  6. rename file as ‘pandoc.lua’.

Hopefully that either clears up the confusion, reveals where I’ve buggered it up, or both.

I’d missed it becuase it flashes by so quickly and is immediately covered by the opening word doc, but a message does pop up from Enhancing Export saying:

image

Sorry I missed that. I don’t know how to disable an error message in the console. My understanding is that the console is just a print-out log rather than active code, so I’m not sure what there is to disable. I experimented with right-clicking the red message but this just gives a context menu saying:

image

None of those look like they would disable anything.

Experimenting with it a little, the red message (“TypeError: Cannot read properties of undefined…”) appears as soon as Obsidian is opened, regardless of which note it opens to. There’s something somewhere in the vault or setup that it doesn’t like. Disabling the Enhance Export plugin does not stop it from appearing on startup.

A new copy of the yellow warning appears whenever I try to export one of these Word docs, and I think is just saying that it can’t read the docx file it’s created (which is fine).

I do appreciate your patience with this frustrating situation, and continued willingness to help… but am I just borked now?

That’s not what happened. You told me you had created a file called pandoc.lua (see for yourself below):

And then you told me you were still calling the filter as zotero.lua:

So I pointed out that this was a mistake, given that if the file is named pandoc.lua, you can’t call it with --lua-filter zotero.lua.

So I said, either rename the file to zotero.lua, or call the filter by its current name, which you had said was pandoc.lua. Either option would make the names match:

I never told you to rename the file to pandoc.lua, because that’s what you told me it was already named.

I recommended option one (as you can see above), namely renaming the file from pandoc.lua to zotero.lua, as this is the name given to the filter by its maker, but you went with option two, which was keeping the file named pandoc.lua, and calling it as --lua-filter pandoc.lua. Whatever, as long as they match.

I meant momentarily disabling the plugins (Outliner and Tasks), of course. But I our takes on the error messages are aligned, in that they aren’t related to the failure to export citations correctly.

I don’t know, there must be something we are missing. Can you try redownloading the zotero.lua filter by going to this page and just clicking link here, which should download the file?

image

I am a bit baffled by why you decided to copy-paste the contents of the downloaded zotero.lua file into a new file called pandoc.lua, rather than just moving the original zotero.lua file into the filters folder in the Pandoc user data directory. Could it be that something went wrong during this copy-paste?

First of all, massive thanks to you @Feralflora ! I’ve been looking for this feature since a long time (as you can see here From Obsidian to Zotero - Zotero Forums)

I’ve followed your teaching and I will share it here, maybe it can help @AlexG.
Just to specified, I’m on Windows, working with pandoc 3.11.1 (to combine it with pandoc-crossref), obsidian V1.5.8, enhancing export plugin V1.10.4 and word 2022. Like @AlexG I use pandoc reference list
I’ve downloaded zotero.lua (without copy and pasting) and I’ve put it in the right folder

In Enhancing export plugin, I selected “Word” export and I put as extra-argument the following :
–resource-path=“C:\Users\mypath to zotero softwar”
–resource-path=“C:\Users\mypath to my bibtex library” (I think not mandatory for this one)
–resource-path=“C:\Users\my path to my vault attachment”
–filter pandoc-crossref (not mandatory, I use it to numbered my captions. Delete it if you don’t have pandoc-crossref installed in the same version of pandoc)
–number-sections
–lua-filter zotero.lua
–metadata=zotero_csl-style:“apa”

In the note I want to export, I don’t even need specific YAML !
Just make sure that the citation with which you want to have the “magic link” in zotero are formatted like this in obsidian : [@citekey]

Then, like @Feralflora said, you will just have to go in zotero tab in the word document that will open itself and select your way of citation in preference “et voilà” you will have your citation in word zotero format.
It will allow you to do your bibliography in word AFTER having completed the exportation from obsidian

I don’t know if it helps, but this topic definitely helped me ! Thanks guys !

1 Like

VICTORY!

I’ve got a version to work!

Only with the most basic lua command, and only with limited formatting options, but it works! YAY!

What was wrong?

It turns out the problem was here:

I had this set to the ‘Markdown’ template.

Why did I do a silly thing like that?

Because a) I didn’t notice ‘Word’ buried in the long list of options, and b) you are asked to select what format you want to convert it to each time you export a file:

Why would it ask you to select your format each time you export a file if that answer is already predetermined, by being locked in from the settings menu? That doesn’t make any sense, so I assumed the template setting was for some other mysterious purpose.

What arguments have I got to work?

At present, only this:
--lua-filter zotero.lua

(yes, I changed the file name back to ‘zotero.lua’ once I learned that it was arbitrary and only had to match in the two places)

What don’t I have working?

If I add even just –metadata=zotero_csl-style:“apa” to my additional arguments field, I get a pop-up error notice. It lists out the (very very long) command it submitted to pandoc, and then adds: “Unknown option -m. Unknown option -e. Try pandoc.exe --help for more information”.

For the record, when I try using the --citeproc command (with the --bibliography tag, etc) I get this same verbose error window, except now the last line reads: “Citeproc: citation cathelat_2019 not found”. I’m not going to bother troubleshooting that, but it is presumably solvable.

What this formatting can and can’t do

YES: “(Jones, 2024)”
YES: “(Jones, 2024; Conquerer, 1066)”
NO: “People like Jones (2024) have argued…”
NO: “(see, for example, Jones, 2024)”

To be fully usable for academic writing it would need to cover all of those options, but that is a battle for another day. Presumably, adding these will require a more sophisticated version of the lua code.

Tidy up answers to @Feralflora on prior miscommunications

All due apologies for the zotero.lua/pandoc.lua naming confusion. I’m sure I wrote the wrong thing in one line, and that set off a cascade of misunderstanding.

When I click the link to the lua filter it takes me to a page that shows the lua code in plain text. I don’t get any options to download the file directly by right-clicking the link, so my only option was to open the page, ‘select all’, and then paste it into an empty text file.

And, to be fair, that did seem to work in the end :slight_smile:

First of all, congratulations!

But man, @AlexG, that’s literally the first pitfall I told you to look out for when switching to Enhancing export:

and again here:

Now it makes sense how nothing was having any effect.

I don’t say this to put you down, but this (and the number of other misunderstandings in this thread) tells me you would really benefit from reading a bit more carefully. Because I really tried to foresee these pitfallls and steer you around them, as you can see above.

See above :point_up:

As for your point b / your question here:

Because it is not predetermined, that’s not what the dropdown is for. It doesn’t determine which format you export to by default, it just lets you switch between export command templates as you configure them.

Like I said in my first message in this thread, each file format you can output to has its own command template. This enables you to customize the command for that specific format. For example, by adding the zotero.lua filter to the Word command, and only to the Word command, because that’s the only place it is relevant.


It seems that you only have one dash at the beginning. You need to have two, as I showed you here:

I suspect you copied it from @Mathunter’s message above, which a) is missing a code fence and b) probably had some form of (iOS) autocorrect that changed -- into an em dash.


Either the bibliography path is incorrectly specified, or the bibliography file doesn’t contain the citekey / item in question (more likely).


I tested your citation examples using the corresponding Pandoc syntax like so:

---
zotero:
  author-in-text: true
  csl-style: apa
  sorted: false
---

## Test conditions

YES: “(Jones, 2024)”  
YES: “(Jones, 2024; Conquerer, 1066)”  
NO: “People like Jones (2024) have argued…”  
NO: “(see, for example, Jones, 2024)”

## Pandoc syntax test

Parenthetical citation follows [@Oreskes.Conway2010DefeatingMerchantsDoubt].

Dual citation follows: [@Oreskes.Conway2010DefeatingMerchantsDoubt; @Brulle2014InstitutionalizingDelayFoundation]

People like @Oreskes.Conway2010DefeatingMerchantsDoubt have argued...

(see, for example, @Oreskes.Conway2010DefeatingMerchantsDoubt)

And got this result in Word (after refreshing the citations):

So seems like number 3 works, and arguably 4 too, as I don’t see why the year shouldn’t be in parentheses in that case. Can you expand on that? And how were you citing, since you got a different result?


I see, must be a browser difference then, because in my case, it automatically downloads when I click that. But in any case, you should be able to right-click and choose “Save link as”.

1 Like

Sorry for side tracking, but this is so true for many of the threads in this forum. It’s so demotivating to give an answer and see they don’t even read the answer, and instead repeats a question on something you’ve already answered.

So kudos to you @Feralflora , and others for being persistent and sticking with it through it all.

2 Likes

Thank you very much for this insightful reply! :smiley:

1 Like

Actually, I didn’t use the right Pandoc citation syntax in example number 4. The following is the right way to add a prefix to the citation to get the result you were after.

So, to get this result: “(see, for example, Jones, 2024)”
you cite it like this: [see, for example, @jones2024]

Which then becomes this in word:
image

In conclusion, all the examples are fully supported using the right syntax.


Yeah, it really is @holroy. It feels pretty disrespectful to everyone’s time and effort. Of course, something can be misread or simply missed, but sometimes it just seems like people going tl;dr, even though some topics just require longer answers. Especially as you dig out from being knee-deep in misunderstandings.

Kudos to you too!


@PedroGonzalez You’re welcome!

2 Likes

[/quote]

And thank you so much for your endless patience!

Formatting references

You are right, the other formatting options do become possible when that front-code is added (it’s YAML, right?). I didn’t want to have to paste this code at the start of every file:

[quote=“Feralflora, post:19, topic:75428”]

---
zotero:
  author-in-text: true
  csl-style: apa
  sorted: false
---

So I did a lot of trial and error with the “Extra Arguments” box, and worked out how to get the same command in there:

--lua-filter zotero.lua
--metadata=zotero_csl-style:"apa"
--metadata=zotero_author-in-text:true

No spaces within the commands or it breaks

Fantastic! You are a whizz. I would never have figured that out on my own.

That is exactly where I got it from. I’d been confused about the em dashes in place of hyphens (I’d been experimenting with trying each in turn)… but of course, it must have been an auto-format thing. That makes so much sense!

Where things went wrong earlier

This is actually something that I can speak to as I’ve literally taught an entire university class on it.

Feel free to skip if this isn’t up your alley. I’m not here to force feed anyone lectures; There is no quiz :slight_smile:

Psychologists have a name for this problem: “The curse of expert knowledge”. It’s hard for experts to explain things to beginners, because they see intuitively obvious layers of meaning, context, and nuance in the words that they say. It is very difficult for them to see how their words don’t carry all this meaning for beginners and they can be very confused as to why the beginners struggle, or misconstrue their words in such obvious ways.

For this reason, companies that build commercial products (as opposed to gold-hearted volunteers who help the world for free) never let their engineers write their instruction manuals. The engineers will tell people to “adjust the upper flanges until they achieve a 3mm tolerance to the outer manifold”, and then will be utterly baffled when beginners don’t follow along with (what they see as) such clear and precise instructions. Companies with budgets employ technical writers to translate this kind of expert-speak into normal English. That might not sound like a necessary job, or even a hard one, but, unfortunately, it very much is.

Take your explanation above:

That paragraph is easy to parse into a clear meaning, but only if you start with a clear picture in your head of what a command template is, what a lua file is, and presumably also what pandoc does, and how those three things interact to translate documents. That context is immediately obvious in your mind, making the paragraph a clear read. But I’m still not quite sure what it means despite reading it three of four times. This isn’t because I’m dumb or being disrespectful, and it isn’t because you are bad at explaining. It is because it’s legitimately hard for humans to communicate across such different levels of baseline understanding. It’s a well-known phenomenon.

If the Enhanced Export plugin was built by a company with big enough resources (instead of being somebody’s labour of love), they would have spent a bunch of money hiring UX experts (User eXperience) to do dozens of hours of user testing: The UX workers would watch consumers try to interact with a series of prototypes, and then tweak the designs until they finessed away any points of confusion. It’s slow, skilled, and time-consuming work but it means you end up with far fewer people like me flailing through patient attempts to solve their problems. To be doubly clear, this is not a realistic ask of smart hackers who are putting tools together on their own, and then letting people use them for free! I realize this!

Please don’t take ANY of this as veiled criticism, or a demand that you do more - not unless someone starts handing you a budget to hire skilled helpers.

I just saw your frustration and thought it might provide a tiny bit of solace to know that we’re not trying to be disrespectful when we struggle with seemingly basic instructions. It’s to your enormous credit that you keep on rolling through these inevitable frustrations and find ways to help people anyway. It’s extra work for you (and the people you are helping), and kudos to you for that.

My hat is off to you, genuinely, and sincerely!