Monica

In the category of "things I posted elsewhere that I want to preserve here"...

Stack Overflow began a documentation project, based on the idea that good examples are the core of good documentation. But the project ran into some problems, so they're "rebooting" it. They're going to focus on a single topic (T-SQL) to start, and are doing some user research before diving in. (And I got some warm fuzzies from the fact that they cited my SEDE tutorial.) But it seemed like some important points about documentation could be missed, things that frustrated me when I participated in the beta of the first attempt, so I weighed in:

---

Documentation doesn't exist in a vacuum; it exists because there are real people with real needs, and there's also prior work.

Regardless of subject, there are a few types of documentation, and when it comes to structure one size does not fit all. For example, there's tutorial-style documentation (like that SEDE tutorial), which introduces concepts as needed (just enough, not too detailed) while walking the reader through a progression of examples, which might have iterative cycles. Another type of documentation is the complete, documented example -- something that the reader can download and run himself, that has good comments and then some doc wrapped around it. (I don't necessarily mean one big <code> block; sometimes it's better to go method by method, for example.) Reference implementations are an advanced form of the complete, documented example.

Then there's conceptual documentation, where you explain in more detail what's going on with the different kinds of JOIN, for instance. And -- perhaps less relevant here, but I'll include it anyway -- there's task-oriented documentation, where you provide step-by-step instructions for how to do something procedural like configure Kerberos. What distinguishes task documentation from documented examples is that there should be fewer decision points -- getting that DB web front end up and running might require 37 steps but they're pretty much always the same 37 steps. That's different from doc about how to optimize a query, where you might be teaching a skill instead of providing instructions.

There's also reference documentation -- think API reference or language spec here -- where the focus is on being complete but comparatively terse, but where examples are also valuable. (This is probably not going to be where our best bang for the buck is.)

My point in saying all that is: these different types of doc require different enabling structures. This doesn't need to be a ton of work, but it's something to think about. We probably want something more than "here's a textbox" and less than "here's the schema for our fancy XML representation" -- maybe we just need some templates? Maybe the question about what T-SQL doc has helped people will evoke answers that touch on structure and organization.

One general point: being able to organize content is important. (Even better if it can be sketched out early on, before all the pieces exist!) In Documentation 1.0 examples on a topic were ordered by votes; there's no way to do a progression that way. A tutorial can involve several examples or example fragments, and they need to be orderable. It also won't make much sense for them to be evaluated (e.g. by reviewers) in isolation, away from their surrounding context. That's great for an initial code review, but you also need to be able to answer the question "is this a good example of that thing we just explained?".

---

That last point, about organization, was my biggest frustration in trying to help with round one of this. Somebody requests examples of Topic X, and a bunch of people throw some code at it, and there's no coordination, no logical ordering, and no way to develop a progressive example. There were lots of people involved but it didn't feel like a collaborative effort. Good documentation requires a little more coordination than that, in my opinion.

Hey, Dreamwidth folks... I've syndicated Universe Factory, the blog of the Worldbuilding Stack Exchange community, here on DW. We started the blog late in 2015; you can see a complete list of posts, including some from me.

Some specific links:

- Fight Earnestly and Hit Them in the Gaps, two articles from a HEMA (Historic European Martial Arts) student.

- Articles on generating rivers, using cellular automata to generate terrain (yes, like in Game of Life), and using distortion fields to generate continents. I believe the author of this series is our first contributor who found us via Medium instead of via Stack Exchange.

- An article on calculating political power.

- Building a Truly Alien Alien.

- When Am I? Navigation for Time Travelers

That's all in the last two months. Among older articles, you might enjoy:

- Building the World of Pangaea, an interview I did with Michael Burstein (mabfan) about the worldbuilding behind a shared-world anthology he was part of (edited by Michael Jan Friedman). That reminds me: wasn't book 2 supposed to be out around now?

- Nature's Oven, a short story.

- Worldbuilding As You Go: A Case Study, which is about how I approached writing The Sisters' War (Chapter 1, summary of the story so far).

- What if the world was (completely) round?

- My Revelation for RPGs series (link is to the index).

TIL #1:

Somebody linked to this question on Stack Overflow about some unexpected results when doing math on dates in Java. The problem, according to Jon Skeet, is that the date being used in the calculation is near midnight on December 31, 1927 in the Shanghai time zone -- when Shanghai moved its clocks by 5 minutes and 52 seconds. So the time in question existed twice, and Java chose the one that the programmer wasn't expecting.

That answers the programming question, but my question from that was: why in the world would somebody move clocks by 5 minutes and 52 seconds? I understand shifts of an hour (that happens all the time), and there are timezones out there that have 30-minute offsets and even one with a 15-minute offset, so that wouldn't have much surprised me either. But 5:52???

So I asked Google, which led me to a question on History Stack Exchange about this, where an answer explained that 1927 was not a good year for political stability in Shanghai, and one of the side-effects was a change in who had control over the central astronomical institution, with the result that the reference point moved east from Beijing to Nanjing. Greenwich was apparently not yet a thing as far as they were concerned.

A comment on the answer, from Taiwan, casts doubt on whether there was a time shift at all -- but, if not, doesn't explain where Java got the idea. Curious.

TIL #2:

A few days ago on Mi Yodeya somebody asked if, during the Exodus, the commandment to place the blood on the doorposts and lintel was just on one door or all of them. (Is it like mezuzot, which are on every door, or like the chanukiyah, which we place next to one door only?) My first thought was that there might have only been one door in ancient Egyptian slave housing. Last night I learned a little about ancient architecture and then wrote an answer about the four-room house, which appears to have had one outside door. I argued that we're given the reason for the commandment: it's to mark which houses are to be passed over. To me, that says blood on exterior doors, of which there was one.

Not TIL #3:

Today on Mi Yodeya somebody asked how many people the Pesach offering would feed. The torah says to use a lamb or kid, that it all has to be eaten that night, and that if you don't have enough people to do that, get together with your neighbors. So how big a group are we talking about? One can find plenty of information (not always in agreement, mind) about the weights of modern livestock animals, but animal husbandry has worked its magic over the centuries -- heck, even within my lifetime we've seen "standard" chickens for food get a lot bigger. So knowing how much a yearling lamb weighs today doesn't necessarily tell us what it might have weighed in ancient Egypt or in the time of the first or second temple, when this was done.

I considered asking on History SE, but I haven't yet. Anybody happen to know?

It's Purim Torah season at Mi Yodeya, where, in addition to the regular, serious questions, we also welcome parody questions. Our policy (yes, we have a policy) says:

It's gotta be distinctly "Purim" (not serious), distinctly Torah, and distinctly Q&A. Purim Torah questions that don't have all three of these qualities may be closed.

So, post sincere-looking questions (you know, the kind that invite answers) that:

• misinterpret a real Torah concept or Jewish text, or
• apply a distinctly Torah style (e.g. Talmudic analysis) to an irrelevant topic

Here's a sampling from this year. Purim Torah is welcome through this week, so feel free to join in.

• If Rabbi Google quotes Mi Yodeya, can i rely on his advice?
• How can I connect with God on Facebook?
• Using the Force on Shabbat, for Jewish Jedis.
• What kind of horns did Moshe have? (my first Purim Torah question)
• Why didn't Adam use the pen of earth? -- based on a misunderstanding of the first verse of the torah and the observation that the pen is mightier than the sword so he should have been able to get back into the garden
• For whom should I vote? (US presidential election 2016), seeking biblical or talmudic sources only
• Seeking texts of all prayers associated with the clock change (also links to other questions about time-shifting)
• What is the bracha when one eats the torah? -- "I keep seeing all these questions which discuss "Purim Torah, Ingest" but they don't seem to address the rules of actually ingesting the Torah." (What's a little homophone among friends?)
• And from the same person who, last year, asked Why don't Jews accept Our Lord and Savior? (I'm pretty happy with my answer there), we have another provocative-seeming question: What's the source/reason for allowing gay marriage for synagogue leaders?

There are a lot more, over 250 from this and past years.

Worldbuilding moderator election: four positions, 19 candidates (ten proceeding to final election), single transferable vote (AKA "Australian ballot", like the Hugos). With the Hugos you're choosing one winner; applying the scheme to a race with multiple winners can get a little odd.

I don't understand all the math, but with multiple seats the algorithm sets a "threshold", a number of votes a candidate needs to win a seat, and excess votes are then transferred away to other candidates to try to determine the next round. ("Meek STV", for those to whom that means something.) If that doesn't advance things then the candidate with the fewest votes drops out and those are transferred to other candidates. Iterate until done.

The first three winners were determined in the first two rounds of vote processing. It took another twenty rounds to determine the fourth. Some of those vote transfers are tiny, as in "I'll take your word for it that there are changes there".

Each voter got three picks but there were four seats. We all expected a lot of jockeying for spot #4 because of that. I wonder how the dynamics would have been different if voters had as many picks as open seats.

The (anonymized) ballot data is available for download. I'm curious about patterns but not quite sure how to look for them.

There is, apparently, a construction company out there that will build you a house styled on a Hobbit hole. Naturally, an important question arises for Jewish owners of such homes: do you put a mezuzah on a round door, and if so where? The mezuzah is the scroll (containing certain torah passages) in a case that is affixed to your doorpost -- so what exactly is a doorpost?

Worldbuilding Stack Exchange is a site for writers, gamers, and others who build settings and have questions about getting the details right. Questions cover a wide variety of topics -- astronomy, biology, chemistry, sociology, urban planning, creature design, magic, and more. Last month we launched a blog for the kinds of posts that don't really fit the Q&A format so well.

One of the requests from the community was posts about how, as a writer or GM, to effectively reveal the interesting details of your world, so you're not just presenting big blobs of exposition or confusing the heck out of people. Some years ago I played in a D&D game that did this really well (run by ralphmelton), so I've started a series of posts about what I learned from that.

Here are the first two: Revelation for RPGs 1: Setting the Stage and Revelation for RPGs 2: The Written Word. Future articles will cover NPCs (there are lots of people in the world who aren't your players' characters; use them well), player meta-game contributions (in this case an in-character journal), prophecy & visions, and geography, at least.

We're finalizing "Days of Awe - Mi Yodeya?", a book of selected questions and answers about the high holy days from Mi Yodeya. I've read the drafts and this is going to be great! We will be placing a printing order next week. I've talked with a few of my readers about this but I'll open it up: do you want a stack of books to distribute at your synagogue this Rosh Hashana? And do you have (or can you get) permission to do so?

If so, please fill out this form by Tuesday, August 11. The information you provide (which, of necessity, includes your shipping address) will only be seen by me and by the person who'll be doing the packing and shipping, who also happens to be the founder of Mi Yodeya. I think highly of him and consider him to be completely trustworthy with that information.

How many copies we print depends on where the crowdfunding project ends up, so you might not get as many as you request, but we'll do our best. Our goal from the beginning has been to spread knowledge, and there are major cities where we don't yet have distribution, so please let us know if you'd like to help us in this.

We probably have to limit this to North America because of postage costs, but let us know anyway if you're interested and we'll see what we can do. Our Israeli distributor is going to print locally instead of us shipping a box. If you're in Israel please let us know where; maybe we can hook you up with that.

The Stack Exchange network has many great Q&A sites, several of which I'm pretty heavily involved with. (I just passed 100k reputation network-wide.) My first and favorite site is Mi Yodeya, the site for Jewish questions and answers. The quality level is very high; I've learned a lot.

SE started with Stack Overflow, for expert programmers, and then added sites for other technical subjects -- programming, system administration, database administration, and the like. Over the years the scope has broadened to include all sorts of topics -- religions, languages, math, cooking, writing, and many more (over 130 of them at the moment). One of these sites is Biblical Hermeneutics (BH).

When BH first showed up I asked why this topic wasn't already covered by the site for Christianity, and I was assured that, in contrast to the religion sites (Mi Yodeya and Christianity, at the time), BH didn't have a doctrinal basis -- the goal was something more akin to the religious-studies department at a secular university. In other words, this was a site for bible geeks, not zealots. I'm a bible (well, torah) geek, so I jumped in.

It didn't work, despite the best efforts of some excellent users -- shining examples of how people should behave there, some of whom I count as friends. Over the three and a half years that it has existed BH has moved from respectful discourse to quite a bit of Christian evangelism and presumption. When nearly every question about the Hebrew bible is answered with the claim that it's talking about Jesus, no matter how inappropriate, it can get pretty frustrating.

BH is a Christian site. Its users refuse to bracket their bias, to write descriptively rather than prescriptively, and to rein in the preaching and truth claims. Opinions masquerade as answers, supported by those who share the opinions and don't stop to ask if an answer actually supported its claims. When that happens you don't have an academic site; you have a church bible-study group. Most people there seem to be fine with that; it's not likely to change.

The site actively recruited Jews. Originally they welcomed us, but the evangelists and those who support them have driven nearly all of us out now by creating a hostile environment. (Last I checked, there was one known Jew there.) It kind of feels like we've been invited to a medieval disputation, except that we, unlike our ancestors, can actually opt out.

In explaining why I no longer felt comfortable there, I wrote:

I don't have a problem with Christians. I have a problem with Christian axioms -- or any other religion's axioms -- being treated as givens on a site that claims to welcome all. I thought we could keep that in check, but now I wonder. [...]

I came to teach and learn in a classroom. But people brought in an altar,
crucifix, and communion wafers, and the caretakers gave them directions.

That was in 2013. Not only did those words fall on deaf ears, but things got worse. I (belatedly) sought rabbinic advice, and it became clear that BH.SE is no place for Jews. I left the site, made (and later updated) this post on Mi Yodeya's discussion (meta) site, and ultimately deleted an account with over 10k reputation.

Other Jews from Mi Yodeya were smart enough to not get very involved there in the first place. But for the sake of other Jews who might come across that site (and this post) I leave this warning: participating there comes with hazards. Please consult your rabbi first.

I'll stay in touch with friends from there in other ways. I wish them the best of luck in trying to bring the site back on track, Herculean task though that may be. I hope it doesn't hurt them. But I'm done.

(I was not planning to make a public post in this journal about this, but some discussions with other SE folks after the deletion of my account persuaded me that I should make one post here.)

These are some pictures from the Roaming Unicorn. Some silliness here, and more to come later in the week I suspect.

( Stack Exchange Roaming Unicorn )

Finally (for now), the Ladycorn joined me at choir practice, where our director, desperate to get us to pay more attention to our hypothetical audience, began conducting with her -- and I was laughing too hard to think about taking a picture. Oh well; some things will just have to be left to memory and imagination.

Yesterday we got word that one of my fellow Stack Exchange moderators (not on a site I moderate, but a different one) had died. I didn't know him well, but we had talked in our moderator-only chat room intermittently, we'd read each others' posts, and I felt like I'd gotten to know him some. It seems like that was mutual. The last conversation we had started with him telling me he respects me "a heck of a lot" (that's mutual) and ended with plans for him to come to Mi Yodeya with a question he was forming. And now he's gone. We found out because somebody -- we don't know who -- updated his profile, and investigation showed it not to be a cruel prank.

I've been on the net a long time, and I still manage to be surprised by how much I grieve people who I may have only known as names and gravatars. But they are still people, people who shared their thoughts and knowledge and aspirations, people I got to know, and online communities -- the ones that are really communities, not drive-bys and transient places to post comments and stuff like that -- cause us to form connections that are every bit as real as those we form with the people we see, speak with, hug. It blows my mind.

And as we grow more and more connected, and frankly as I get older and have online friendships that stretch from years to decades, I know there's going to be more and more of this. Affable Geek wasn't the first in my digital life by far, he won't be the last, and we knew each other only casually, and yet his passing still touches me deeply. I still expect to see his digital face pop up on the network, but it won't any more.

I asked a question over on the Community Building site on Stack Exchange and I suspect some of my readers might be interested or even have relevant knowledge: Detecting and preventing hostility to women? Excerpt:

I recently had a conversation with one of the users who stood by during [personal attacks directed at me], in which he said approximately: "Well what did you expect? That's how guys work -- if a woman pushes back against a guy all the other guys are going to rally to his side".

It's true that I was one of the only identifiable women -- perhaps the only identifiable woman (don't remember now) -- on the site at the time. In the 21st century and in an online community not prone to attract teenagers (the average age was probably over 30), it never occurred to me that this could be an issue. Some of the ad-hominem attacks I received take on whole new meanings in light of this.

How much does this still happen? (Any recent research?) And if I'm in a community where I don't think this is happening to people (but who knows, maybe I'm just blind), how do we keep it from happening?

Most of my online communities are well-behaved, polite, and AFAIK gender-, race-, and religion-blind. But not all communities are, obviously.

Tonight begins Chanukah, and for the occasion the Mi Yodeya community has published its third holiday-themed collection of high-quality questions and answers. This one includes one double-sided page for each of the eight nights, with a little something to read after lighting candles or while enjoying your latkes. Questions cover everything from history to the laws of Chanukah to practical tips (like how do you clean an oil-based menorah?), and you don't need to be an expert to understand the answers -- these are written for everybody from beginners to scholars. I'm really pleased with what we've put together and I hope you'll enjoy it too.

Download it from http://s.tk/miyodeya (or read it online there). Enjoy!