This minor NarraFirma release is a very minor one. It does only two things:

1. It fixes two mistakes I made while getting the 1.1.12 release ready (the version was wrong in the WordPress readme file, and the “tested up to” WordPress version was also wrong).
2. It improves the description of NarraFirma on the GitHub readme page. More specifically, it brings the description up to speed with the new Working with Stories books. (I noticed this when I was fixing the typos.)

Note that I have not updated any of the NarraFirma screenshots (for WordPress or GitHub). They are (apparently) from 2017, but they are not that different from what the software looks like now.

As always, if you find any bugs – or find anything in NF confusing or hard to use – please tell me on the GitHub issues page.

This minor NarraFirma release contains one speed improvement and several interface improvements.

Better loading speed

The fees of the hosting provider we have been using to host all of our web sites for two decades have been going up and up. So we decided to save some money by moving narrafirma.com (with its demo version of NarraFirma) to a cheaper hosting service. After we did that, we discovered that NarraFirma would not load and gave us an error. It turned out that the cheap managed WordPress service we had chosen was rate-limiting NF’s client requests for messages, allowing only so many requests per second. Our old hosting service did not do this, so it was a lucky break that we were able to see an error that our users might have been seeing that we had not.

When we built NarraFirma in 2014/15, we had the client part of the software request 100 database records from the server at a time. That worked well then, but today, some managed WordPress servers (like the one we tried out) limit how many requests a client can make from a server per second (to cut costs). That’s what we were seeing: rate limiting. We fixed the error by changing the NarraFirma client to ask for 1000 database records at a time, thus spacing out the requests over longer time periods. The greater size of the bundle did not (and should not) cause a problem because most of the records are very small.

We decided not to keep the site on that server, mostly because I didn’t like the way they managed their WordPress sites, and in the end we saved some money by installing my new Story-Colored Glasses blog on the same server as NarraFirma is on.

The only change you are likely to see in NarraFirma is that it should now load faster. We considered making the request size configurable (instead of changing the hard-coded 100 to 1000), but it’s probably not necessary to burden you with a decision like that. If you ever see an error when you are loading NarraFirma, please do tell us about it.

Updates for the fourth edition of Working with Stories

We found and fixed the rate-limiting problem in … I’m going to say February. But I didn’t find the time to put out a new release until the end of April. That was because, as a rule, I try to make at least one small visible improvement to NarraFirma at least once a year, to prove that it hasn’t been abandoned, and the 100-to-1000-messages change wouldn’t be a visible change. So I went looking for something visible to change.

I soon realized that I should update NarraFirma to match the new fourth edition of Working with Stories. These are the things I changed:

• I changed the image-map diagram on the home page of NarraFirma (and on its help system) to match the new diagram in WWS.
• I changed the labels and order of some of the PNI planning questions to match my new explanation of the questions in the planning chapter of WWS. (Your data will not be changed.)
• In the help system, I changed every excerpt from WWS3 to a similar one in either WWS4 or WWS Simplified. That was boring and tedious but necessary. Now the book and software match (mostly) again.
• In WWS4, I moved the story-sharing assessment tool to the new Miscellany book. As I did so, I changed one of the questions in the tool. It used to be called “Real stories” and read “Did you see people tell stories that were recountings of events based on emotional experiences from particular perspectives?” Now it is called “Habitation” and reads “How often did it seem to you that people inhabited the stories they told?” In this new NF release, I decided to ease the transition between these two questions by combining them thus: “How often did it seem to you that people inhabited the stories they told? That is, how often did their stories recount their own experiences from their own perspectives?” I think that change will preserve the meaning of legacy data while providing an opportunity to think through the new question.

I decided not to change every term I changed when moving from WWS3 to WWS4. I don’t want to confuse NF users, and also, some of the words are in your data as well as in the NF interface. Backward compatibility has been an important consideration with every change I have ever made to NarraFirma. If you created a NF project in 2015, you can still open and use it in 2026. That is important to me.

These are the terms I changed in WWS4 but not in NarraFirma:

• In WWS4, I no longer talk about “catalysis reports.” I decided the word “report” seems too authoritative and less open to challenge. Now I just call what you produce in catalysis “catalytic material.” But the term “catalysis report” is all over NarraFirma, including in your data, so I have left it alone.
• In WWS4, I no longer talk about “story forms.” I decided that was too esoteric. Now I just call the things you use to ask people for and about stories “sets of questions” or “question sets.” But “story form” is all over NarraFirma, including in your data.
• In WWS4, I no longer talk about “group story sessions.” I now make a clearer distinction between “group interviews,” in which people share stories but do not participate in exercises, and “story-sharing sessions,” in which people take part in game-like exercises. In NF the terminology is of “story collection sessions,” and “activities” such as group exercises are optional. I left that alone.
• In WWS4, I stopped using the term “eliciting questions” in favor of the clearer “story-eliciting questions.” NF calls story-eliciting questions “eliciting questions.” I did not change that.
• In WWS4, I changed “narrative incident reports” to “narrative incident accounts” (see previous discomfort with the word “report”). I decided not to change this term in the recommendations system of NarraFirma because I think it might be in some people’s data.

Quality-of-life interface improvements

Every time I come back to NarraFirma to give it another week or two of my time, I hate how it looks. It’s a dated interface. It was dated when we first released it in 2015. That’s okay. NarraFirma is free, useful, and reliable. I don’t think reasonable adults need their software to be dumbed down and full of eye candy. Sure, yes, if we got a huge grant to make NarraFirma better, I would want to use some of the funding to build a better-looking and easier-to-understand interface. But since that’s probably never going to happen, it’s fine the way it is.

Still, every time I come back to NarraFirma, the ugliness of it nags at me, and I look for a few things I can tweak (in the time I have) to make it look just a bit better. This time I changed a few things that should make NF a bit more approachable.

• I expanded the one-word headings on each section page to several words. I was trying to be succinct when I wrote the headings, but I can see now that they were confusing. So now, in the Planning section, for example, “Orient” has become “Start planning your project,” and in the Collection section, “Collect” has become “Gather your stories.” That makes much more sense.
• I indented the page names on the section pages. This was my husband’s suggestion when I told him that people are annoyed and confused at seeing so many page links in a row. I think it looks better his way.
• I spent some time revamping the page-category icon system. I moved the icons to the left of the page names so they line up in a vertical row. I gave each page only one category icon, and I changed some of the icon assignments and added some more categories. I think the icons will be more helpful now, though you can still turn them off (in Project administration).
• I added some filler words to some of the page names for better readability. For example, in the Planning section, “Build privacy policy” has become “Build your privacy policy.” When it comes to readability, more can be less.
• I added some lines to the home page to make a clearer distinction between the menu of sections (the PNI phases diagram) and the “Quick links” for the current project. This was my son’s idea. I said to him, “People are confused by this main page. They say it’s too busy, and they are overwhelmed by it.” So he was like, “You should divide it up like this.” And he drew those lines for me. So I implemented them, and he was right, it looks much better now. He also helped me to improve my PNI-phases diagram in WWS4 (and now in NF). He has a great sense of design.
• I took the tips off the bottom of the home page. They are useful on other pages, but they are too much of a distraction on the home page.
• I squeezed down the top-of-page header a bit, to keep it more out of your way.
• I removed the trademark symbol from the word “NarraFirma” at the top left (it was distracting) and made the word into a link to the home page (for the current project).
• I changed the colors of the arrow buttons at the bottom of each NF page. For a while I had thought they created too much of a distraction from the body of the page, so I had changed them to blue. But this time through I realized that the blue buttons were confusing. So now they are orange again.

As always, if you find any bugs – or find anything in NF confusing or hard to use – please tell me on the GitHub issues page.

This minor NarraFirma release contains several slight prettifications. All of them were occasioned by my going over all the images from NarraFirma in my new edition of Working with Stories to make sure they are clear and understandable. I didn’t like how some of the graph fonts and spacings looked in the book, so I changed the software to make them look better – for me and for you. There’s nothing like a different context to make you see things differently!

No more shouty graph titles. I changed all of the graph titles to lower case. Now they will look exactly the way you entered them. Ten years ago I thought upper-case titles made NF’s graphs look more professional. Now I think they are ugly and distorting. If you liked the upper-case titles, you can put them back. On the “Configure catalysis report” page, in the advanced options, under “Custom CSS,” add this line:

.narrafirma-graph-title { font-variant-caps: small-caps; }

Bigger label fonts. I increased the size of every font on every graph – not a lot, just a little – for better readability. You can override all of these new settings using the Custom CSS feature (but I think you won’t want to).

More no-count graph options. There has long been an option to hide the story-count numbers on contingency graphs. I’ve now added the same options for bar graphs and histograms. For histograms, you can set the option separately for single and subgraph (histogram set) versions.

Better bar-chart count label. I changed the bar-chart y-axis label from “Count” to “Number of stories.” The things in the columns of bar graphs in NF are always stories, even if the questions are about people. I think this labeling might be more clear for the people who look at your graphs. This new label also draws attention to the fact that the little alternating-color boxes on the graph are stories, which (in NF) you can hover over and read. (I think a lot of people don’t realize that.) Note that if you previously entered a catalysis-report translation for the “Count” label, and you don’t create a new translation for “Number of stories,” your graphs will still show your old translation of “Count.”

This example shows all four of the above changes (better title, bigger fonts, hidden column counts, changed y-axis label):

Bold axis names. I decided to draw all axis names (x and y) on all graphs in bold. I noticed that they were a little too easy to overlook or forget.

Better positions for subgraph names. For histogram sets and scatterplot sets, I had originally put the names of the subgraphs (e.g., Feel about: happy) in the axis labels. That never looked good to me! But I had to do it because otherwise the subgraph titles were not included in the exported PNG or SVG files (because they were outside the SVG structure). I have now fixed that, by drawing titles for subgraphs within the SVG stucture.

Boxes around subgraphs. I felt that subgraphs (in histogram sets and scatterplot sets) were easy to confuse with each other, so I put thin little boxes around subgraphs. Now, I think, it is more clear what each smaller graph shows.

This image shows the previous three changes for histogram sets (bold axes, subgraph titles, boxes, plus no column counts):

This image shows the previous three changes (bold axes, subgraph titles, boxes) for scatterplot sets:

A few other tweaks:

• On the “Configure catalysis report” page, I changed the “tables” graph type to “contingency tables.” That’s less confusing. It still says “tables” on the “Type” column in the “Explore patterns” page. That’s harder to change.
• I increased the default graph width (which drives every other size) from 800 to 900 pixels. Screens are bigger now. You can set any graph width (and height) in the advanced options, but the default is a little higher now.

Font scaling bug fixed. Lastly, I fixed a longstanding bug in the PNG file export of graphs. It’s not a fix, really. It’s just a workaround for a bug in the (very old) version of the canvg library NarraFirma uses to create PNG files from SVG (vector) graphics. The fonts on those files have always come out smaller than they should. So in this version I brute-force increased the font sizes in all PNG-exported graph images. (I had added a user-supplied “percentage modifier” to increase font sizes in reports a long time ago, but I suspect that few users have noticed it.)

The real fix for this problem will be to update the canvg library version we are using. Canvg is one of several libraries we are using in out-of-date versions from 2015 (or so). We would like to update all of them. However, updating each one will require us to update each piece of library-calling code to comply with current usages. We will also need to do a lot of regression testing to make sure we haven’t broken anything (for new or legacy projects). I hope we will eventually find the time to do it. In the meantime, NarraFirma still works fine with the old versions of the libraries, and Paul says HTML is pretty strongly backwardly compatible, so we should be fine. Probably.

As always, if you find any bugs – or find anything in NF confusing or hard to use – please tell me on the GitHub issues page.

This minor NarraFirma release adds a few new features and fixes a few bugs.

Your win-win proposal(s)

I realized that NF did not give you an opportunity to write and record win-win proposals: things you want to say to potential project participants. So I added a section with some questions to help you do that. You will find it in the “Describe participant groups” page.

Slightly easier translation options

A user reported a bug, and while we were fixing it, we noticed that they had entered a translation language, entered some translated texts, then changed the name of the language. Because the translation facility in NF relies on a simple lookup function linked to a language name, they then had to re-enter all of their previously translated texts. That seemed like a pain. So I added functions to rename and remove language entries en masse.

On the “Translate story forms” page, you can find these new functions (“Rename language” and “Remove language”) in the list of things you can do next to the “Do it” button. Because these functions reach into and change dictionary entries across all of your translated story-form texts, I suggest that you export your translation dictionary before you use them, in case you make a mistake (or I did).

On the same page, I also changed the counts of translated texts shown below the “additional languages” box. Any translations that are not visible on the page because you renamed or removed a translation language in the “additional languages” box (without using the rename/remove functions) are now counted and marked as “hidden.”

Better error reporting for renamed or removed questions

The user who reported the bug also renamed a few questions, causing some rather cryptic errors to appear when their story form was being shown. I improved the clarity of the error messages.

I also added a flag to the question lists on the “Build story forms” page. The new flag (“NOT FOUND in project”) tells you that a question you have included in your story form no longer exists in the project (because you have renamed or removed it). You should remove these questions from your form (press the > arrow), because until you do, you will keep seeing errors in your console every time you use the form.

Now for the bug

This was a pretty big bug, but it only appears in a very specific situation. This user (the same one as above) created two choice questions.

• One had numbers for answers: 1, 2, 3, etc
• Another had number ranges for answers: 1-25, 26-50, etc

They used these questions in a form, associated it with a story collection, then added some translations to it. Then they tried to update the form connected to the story collection. NarraFirma spat out an error message and refused to update or display the form, stopping them from collecting any more stories.

After some investigation, we discovered (to our surprise) that the hash method we were using to verify the security of the transmitted data was slightly different whether it was PHP doing it (within the WordPress server) or Javascript doing it (in the browser client). More specifically, the JSONification method in the Javascript code sorted their data structure differently than the most recent versions of PHP sorted it. That was what caused the error message: sorted data structures (thus hashes) that didn’t match. We never saw it happen before because to see it you had to have two sets of entries that might or might not sort together (1, 1-25, 2, 26-50, 3) or separately (1, 2, 3, 1-25, 26-50).

So Paul changed the Javascript method to bring it into synch with the PHP method. It fixed our user’s bug, and we tested the change with some legacy projects, so we think it will not cause any problems for anyone.

NF is getting out of date

That bug happened because the NF code is pretty old and is getting out of synch with the rest of the web. We really ought to go over it with a fine-toothed comb to bring it up to date with respect to a lot of things that have changed since we first released it in 2015. We are probably not going to be able to do that unless we get more funding to work on it.

If you want NarraFirma to continue to be a useful tool, please make a donation to support it. Without more donations, the best we can do is to fix each problem as our users find it. We intend to do that for as long as we can.

A few smaller bugs

We also discovered that:

• There were a few places in our PHP code where there should have been return statements. It probably didn’t create any problems, but it’s better now.
• The Node.js site admin page was confusing in a few places. We fixed it.
• We improved another error message that appears when a question is missing.

In general we are always trying to make our error messages more clear, so you know what is going on. If NF ever does things you think it should not do, look at your browser console! There is usually something written there.

As always, if you find any bugs – or find anything in NF confusing or hard to use – please tell me on the GitHub issues page.