How Federated Wiki neighborhoods grow and change

Federated Wiki sites form neighborhoods that change dynamically as you navigate FedWiki space. Sites that are within your current neighborhood are special in two ways: you can link to them by names alone (versus full URLs), and you can search them.

Here’s one neighborhood I can join.

A row of flags (icons) in the bottom right corner of the screen (1) indicates that there are five sites in this neighborhood: my own and four others. The number next to the search box in the bottom middle (2) says that 772 pages can be searched. That number is the sum of all the pages in the neighborhood.

From each site in the neighborhood, FedWiki retrieves a summary called the sitemap. It is a list of all the pages on the site. Each item in the list has the page’s title, date, and complete first paragraph (which might be very short or very long). FedWiki’s built-in search uses sitemaps which means that it only sees the titles and first paragraphs of the pages in your neighborhood.

Here are the sites in this neighborhood:


You can find these names by hovering over the row of flags. If you are technical you might also want to observe them in a JavaScript debugger. In this picture, I used Control-J in Chrome to launch the debugger, then clicked into the Console tab, then typed the name of the JavaScript variable that represents the neighborhood: wiki.neighborhood.

Why are these five sites in my neighborhood? It’s obvious that my own site,, belongs. And since I’ve navigated to a page on, it’s not suprising to find that site in my neighborhood too. But what about the other three? Why are they included?

The answer is that Ward’s page includes references to,, and A FedWiki reference looks like a paragraph, but its blue tint signals that it’s special. Unlike a normal paragraph, which you inject into the page using the HTML or Markdown plugin, a reference is injected using the Reference plugin. It’s a dynamic element that displays the flag, the page name, and synopsis (first paragraph) of the referenced page. It also adds that page’s origin site to the neighborhood.

Two of the five sites in this example neighborhood — and — got there directly by way of navigation. The other three got there indirectly by way of references.

To add a reference to one of your own pages, you click the + symbol to add a factory, drag the flag (or favicon) of a remote FedWiki page, and drop it onto the factory.

To illustrate, I’ll start with a scratch page that has a factory ready to accept a drop.

In a second browser tab, I’ll navigate to’s Ward Cunningham page, the one with the three references we saw above. Then I’ll drag that page’s favicon into the first browser tab and drop it onto the factory. Dragging between browser tabs may be unfamiliar to you. It was to me as well, actually. But it’s a thing.

The setup in this example is:

Tab 1:

Tab 2:

Here is the result:

How many sites are in this neighborhood? When I did this experiment, I predicted either 2 or 5. It would be 2 if the neighborhood included only my site and the origin of the referenced page. It would be 5 if FedWiki included, in addition, sites referenced on the referenced page. Things aren’t transitive in that way, it turns out, so the answer is 2.

Except that it isn’t. It’s 3! Look at the row of flags in the bottom right corner. There are three of them:,, and mysteriously, That’s Paul Rodwell’s site. How did he get into this neighborhood?

This closeup of the journal will help explain the mystery. The page was forked 5 days ago.

We can view the source of the page to find out more.

And here’s the answer. Early in the life of my scratch page I forked Paul Rodwell’s scratch page from

So we’ve now discovered a third way to grow your neighborhood. First by navigating to remote pages directly. Second by including references to remote pages. And third by forking remote pages.

19 thoughts on “How Federated Wiki neighborhoods grow and change

  1. This is really helpful. I think I get it. I think I can try it at least.

    But it takes me back to my ongoing question about the naming of parts. Site – page – neighbourhood – factory – fork – reference – flag – journal. So in FW we have spatial and technical metaphors working together, and for me as a user without a technical background, this increased the confusion.

    It’s one of the many ways in which FW reminds me of Moodle. (Just google: “scroll of death”.)

    The naming of neighbourhood, factory and journal seem to me the most idiosyncratic here — the other terms are all in general use, even if not actually used by me. I’m interested to know more about where they came from as ideas — about the cultural work they’re asked to do as metaphors. Factory is the most offbeat; neighbourhood seems to me to be working very hard to de-emphasise factory; and journal is something other than the journal of “December Journal” or “journalling”.

    Also perhaps of interest, for many non-STEM writers like me “synopsis” and “first paragraph” aren’t necessarily the same. So if they are to achieve the ideal function in FW of the first par being the searchable synopsis it means perhaps developing a writing style that treats them that way. But I think something could be lost if FW pushes towards template driven writing.

    Much thinking.

    1. Factory comes from the world of programming. In that world it’s a common pattern to have families of things that share common characteristics. That commonality is abstracted into another thing called a factory. I agree that it is not the best term to present to most users. A more familiar term would be widget. Or rather widget maker for factory, and widget for the plugins that the factory injects into the page.

      Journal again is infused with a programmers’ sensibility. When a database keeps track of transactions — that is, operations that add, change, or remove data — the log of those transactions is called a journal. That’s what the journal in a FedWiki page is. But it does invite confusion, since in FWH we were also encouraged to write journals in the everyday sense: prose narratives of our day-by-day activity. A less ambiguous term for the FedWiki transaction journal might be page history.

      Good point about synopsis also. It does imply synthesis but in this case there is none. I personally like the term lead paragraph. Formerly only journalists needed to care about “heads, decks, and leads” but now we are all writing stuff that surfaces in a variety of contexts. Sometimes only our headlines will appear, sometimes only headlines and lead paragraphs. It’s a good general discipline to take special care when writing those elements.

      I have no interest in template-driven writing. I am very interested in FW as a means of doing what I did with your essay: exploring its evolution, surfacing alternate possibilities, comparing and discussing them.

  2. My head is spinning. I’d missed the technical history of factory completely, although I did sense that journal had some kind of technical association with the thing I see in FW.

    So where “grok” alerted me by its complete strangeness to the fact that I should get around to looking it up eventually, and “fork” alerted me by the way it was used to the probability that it didn’t mean fork in the way that kept coming to me (as a gardener — to fork is to fork over, to turn), “factory” gave me no clue that there was something I was missing. I just assumed it was a spatial metaphor in an oddly scaled relation to neighbourhood.

    (OK, so please tell me neighbourhood is just a spatial metaphor.)

    I’ve noticed others who’ve written about SFW found the language contributing to their confusion. This suggests two options, one of which is to rename some things; and the other is to write a built-in glossary of really clear explanations of terms. The issue is that so much of the explanatory conversation takes fluency with these terms for granted.

    Interestingly I thinks me of these terms are also generational. So widget is familiar to me but I learned the other day that it’s not familiar to students. So telling them “it’s ok, it’s where you make your widgets” would induce a kind of pitying look.

    In simplest terms, I came to understand factory as a kind of workbench: here are your tools and ingredients. Like you, I see the journal as “history”. Neighbourhood is folksy but actually falters as a metaphor for these flexible and contingent gatherings.

    Jon, thanks so much for taking all these questions. I’m learning a lot.

    1. Interesting point about widget. If your students have experience with WordPress or Tumblr it will resonate. But if their point of reference is primarily Facebook the only analog is app which doesn’t really fit.

      Neighborhood may have a technical antecedent as well. Network Neighborhood ( was once an official term in Windows. It referred to the computers visible on your local area network (LAN). And that neighborhood was also dynamic, changing as computers joined or left the network. Even though not an official term in Mac networking, it’s used informally in the same way (

      I think neighborhood is exactly right for SFW. The SFW neighborhood is more dynamic than local area networks but I would think the experience of LANs should be a conceptual bridge. Not so for you?

      A glossary is a great idea. Would you like to start by creating [[Federated Wiki Glossary]] and populating with the terms you find problematic, and your best current interpretation of them? I’ll be happy to help.

      There will be two challenges. First, which (if any) copy of the glossary will represent our consensus? We’ve talked about this a lot, there’s no straightforward answer, and that in itself is one of the big challenges. However I’ve watched [[All 2014 Happening Blogposts]] ( evolve in an orderly way, so we are getting the hang of it.

      The other challenge, of course: neighborhood vs neighbourhood :-)

  3. I wondered, after reading Jon’s explanation, whether the neighborhood was a characteristic of the site, or whether it was a characteristic of the pages I was presently viewing (on a site).

    In navigating around a bit, it became apparent it was the latter. Well, at least not the former. The faces/gradients in the neighborhood are apparently accumulative. For instance, if I start on Jon’s Welcome page:

    I see three in the neighborhood.

    If I subsequently navigate to John’s Happening Folks page I see (lots):

    Then if I navigate back to his Welcome page, the neighborhood does not shrink. It keeps all the happening folks (sites).

    If I refresh the browser tab while viewing his Welcome page in the far right card, the neighborhood narrows again to three.

    So the neighborhood seems to be the accumulation of all the sites “encountered” (navigated to, referenced by, forked from, as Jon describes above) in this “session”. A session starts at a browser page load/refresh and continues indefinitely I suppose.

    The neighborhood behavior would be less surprising if it were not accumulative. I expect the neighborhood to reflect what is showing on the page, or to reflect the neighborhood of the site, not the history of my navigation session. Perhaps, though, the neighborhood is useful in ways I do not guess.

    1. I think you’ve put your finger on it. Accumulation is unexpected and unfamiliar. Ward and his team, and Mike Caulfield who has been SFW’s best evangelists, have intuitions about how it’s useful. I do as well but can’t yet explain them well.

      The Happening that Mike organized was really a shakedown cruise for SFW, the first time it was used to support a directed group exercise.

      The first thing Mike realized was that he had to seed a neighborhood with the invited participants, which he did by creating a well-known page (Happening Folks) full of references to their bios. There remained two challenges. First, people had to visit that page, and since it currently loads referenced sitemaps laboriously (this is fixable), it takes a while for the whole neighborhood to form. Second, since the Happening Folks page was distributed like all others in FedWiki space, the initial intent to collaboratively evolve it failed. (With more experience I think it could have worked, as a more recent example mentioned elsewhere in these comments did.)

      Later Ward created Conversation Clubs (, a server-built view of activity in the neighborhood defined by the references on the Happening Folks page.

      These two efforts to codify neighborhoods were necessary and instructive. At larger scale, will accumulation of “sites encountered” be useful in ways that I (at least) cannot predict? Ward and Mike think so. I am undecided but curious.

      1. In thinking about the “accumulation” behavior (for neighborhoods) a bit more, perhaps the reason it is so surprising is because it breaks an implicit rule of the modern web application, to wit, that the page shouldn’t change when your (manually) refresh it.

        If a web page changes when you manually refresh it, there is a shortcoming in your app. Sometimes these shortcomings arise out of expediency, the canonical case being failing to update shared state on the page in real-time. Other times they are the result of architectural oversights or plain old bugs, e.g. I add an item to a collection in one part of the app, and then I have to refresh a page to see the new item in another part of the app

        Of course very few significant apps ever achieve consistency-across-refresh nirvana. But we developers do try hard (and harder) to make it so. What’s so surprising in the case of SFW neighborhoods is that the accumulative behavior seems to be there on purpose.

      2. I’m missing something here. Consider It loads a neighborhood of 5. Refreshing the URL reloads the same neighborhood of 5. If navigation extends the lineup in a way that grows the neighborhood then refreshing the URL recalls that expanded neighborhood.

        (Things might change if, between refreshes, one of those pages added a fork or a reference.)

        If I then navigate back to, though, the context I’ve accumulated is blown away, and it is hard and expensive to recreate it. Since that context governs what I can search, and what links I can resolve by name vs fully-qualified URL, I’ve wondered about preserving that context unless I explicitly release it.

        But as I said, I think I’ve missed your point and would like to understand it properly.

      3. This may depend on what you mean by “Then if I navigate back to his Welcome page, the neighborhood does not shrink.”

        In your example, yields a neighborhood of 1 (not 3 as before, I’m not sure why.) Then:

        1. yields a neighborhood of many.

        2. preserves that neighborhood of many.

        3. reduces it to one again.

        2 and 3 are different ways of “navigating back” to the Welcome page: 2 being lineup-preserving, 3 not.

        Is that the distinction we’re after? I’ll freely admit I’m still grappling with the dynamics of the lineup as a pipeline.

      4. Heh. Yeah, rereading my example I can see how confusing it is. Let me try a different way.

        I load this URL:

        And I see a neighborhood of 1.

        Then I click on the link to Happening Folks on that page and now my URL is:

        and I have a (large) neighborhood (on the order of say 30 avatars).

        I now have two cards in my browser.

        On the left card (Jon’s Welcome page) I click the “January Journal” link and the URL changes to:

        and the right-most card is replaced (was Happening Folks, is now January Journal).

        At this point my neighborhood is still large (on the order of 30 avatars). However if I refresh the page (to reload URL I drop back down to 1 avatar again.

        The issue is that depending on my activity leading up to my arrival at when I’m on that lineup, the neighborhood I see, depends on how I got there. If I load the URL directly my neighborhood is 1. If I got there in the web app with an intermediate visit to Happening Folks then my neighborhood is (big). When I have that big neighborhood, a manual page refresh drops the neighborhood back down to 1.

      5. Gotcha. Yes, thanks for reminding me. There’s a kind of internal navigation that’s context preserving until you refresh and then it’s gone.

        Should it persist across refresh? If so, how would you prune or remove it?

        I don’t have answers, just wondering out loud.

  4. This is helpful. Thanks. I agree that the meaning of “page history” is clearer than “journal”. “Save” might be better than “fork”, since you sometimes need to fork your own pages to make an edit permanent. “Factory” is appropriate, but “factory box” might help newcomers understand what we’re talking about.

    One of my Fedwiki-beginner wishes has been greater control over my current neighborhood. But apparently, separate pages of collected References will provide that already.

  5. Oh wow, I just noticed that a Recent Changes page is not kidding when it claims to “…list neighborhood pages with those most recently changed listed first.”

    I navigated to Jon’s Recent Changes and the recent changes were all by Jon (I saw his face).

    Then I navigated to his Open Letter To Mike and I noticed that the Recent Changes card (to the left of the newly-opened one) updated and now I had lots of different recent changes by lots of folks. And lo, my “neighborhood” had grown. And that’s why the recent changes changed—because by opening the Open Letter To Mike the neighborhood (in my session) had changed.

    Surprising but consistent. Interesting.

    1. FedWiki is wildly dynamic along every axis. Full of surprises like that. A big part of the challenge, as I see it, is to separate the delightful from the not-delightful surprises, and showcase the former while minimizing the latter.

      One thing that got out of control in the Happening was the Happening Folks page. So now there are many versions of it floating around. If you try loading alternate versions of it from Recent Changes your neighborhood will churn like crazy.

      My favorite reaction to FedWiki: “Then Salvador Dali showed up, and all the clocks melted.”

    1. Nice! Alternatives to Facebook are much needed, this seems like a good one. Not available yet outside Vermont, it seems.

      Coincidentally I was invited today to join Nextdoor which exists and is well-subscribed in my town (and neighborhood).

      This recent update is notable:

      I struggle with the idea that it should be necessary to join /any/ closed, user-data-vacuuming network to accomplish these goals. But I guess this is way off the topic of federated wiki neighborhoods.

      Or is it?

  6. This post lays out information that seems to be very important for understanding wiki but is lacking in the getting started info at I forgaged around and couldn’t find, especially, instructions to reference another site. It’s an unintuitive task but critical for taking advantage of federation.

    Further, references are not discoverable in the factory UI or by editing an existing reference. I wonder if an explicit link in the item factory has been considered.

  7. This page describes critical information for understanding core capabilities of federated wiki and I hope it can be featured in the intro at and default new wiki installations. Correct me if I’m missing it, but I foraged from and searched but could not find instructions for referencing another site, other than here and in Mike’s helpful blog post on setting up a classroom farm. Dragging a flag from another browser tab is doable (on a PC) but awkward and totally undiscoverable. Further, references are not discoverable via the factory or by attempting to edit an existing one, which would be handy for figuring out how they work and for creating a reference by copy/paste URL.

Leave a Reply